1CIFS.UPCALL(8)                                                  CIFS.UPCALL(8)
2
3
4

NAME

6       cifs.upcall  -  Userspace upcall helper for Common Internet File System
7       (CIFS)
8

SYNOPSIS

10          cifs.upcall [--trust-dns|-t] [--version|-v] [--legacy-uid|-l]
11                      [--krb5conf=/path/to/krb5.conf|-k /path/to/krb5.conf]
12                      [--keytab=/path/to/keytab|-K /path/to/keytab] {keyid}
13

DESCRIPTION

15       This tool is part of the cifs-utils suite.
16
17       cifs.upcall is a userspace helper program for  the  linux  CIFS  client
18       filesystem.  There  are  a  number of activities that the kernel cannot
19       easily do itself. This program is a callout  program  that  does  these
20       things for the kernel and then returns the result.
21
22       cifs.upcall  is  generally  intended  to  be  run when the kernel calls
23       request-key(8) for a particular key type. While it can be run  directly
24       from the command-line, it's not generally intended to be run that way.
25

OPTIONS

27       -c
28          This option is deprecated and is currently ignored.
29
30       --no-env-probe|-E
31          Normally,  cifs.upcall  will probe the environment variable space of
32          the process that initiated the upcall in order to fetch the value of
33          $KRB5CCNAME.  This  can  assist  the program with finding credential
34          caches in non-default locations. If this option  is  set,  then  the
35          program  won't  do  this  and will rely on finding credcaches in the
36          default locations specified in krb5.conf. Note that  this  is  never
37          performed  when  the  uid  is  0.  The default credcache location is
38          always used when the uid is 0, regardless of the  environment  vari‐
39          able setting in the process.
40
41       --krb5conf|-k=/path/to/krb5.conf
42          This  option  allows administrators to set an alternate location for
43          the krb5.conf file that cifs.upcall will use.
44
45       --keytab=|-K=/path/to/keytab
46          This option allows administrators to specify a  keytab  file  to  be
47          used.  When  a  user  has  no  credential cache already established,
48          cifs.upcall will attempt to use this keytab  to  acquire  them.  The
49          default is the system-wide keytab /etc/krb5.keytab.
50
51       --trust-dns|-t
52          With  krb5 upcalls, the name used as the host portion of the service
53          principal defaults to the hostname portion of the UNC.  This  option
54          allows  the upcall program to reverse resolve the network address of
55          the server in order to get the hostname.
56
57          This is less secure than not trusting DNS. When using  this  option,
58          it's  possible  that  an attacker could get control of DNS and trick
59          the client into mounting a different server altogether. It's prefer‐
60          able  to instead add server principals to the KDC for every possible
61          hostname, but this option exists for cases where that  isn't  possi‐
62          ble.  The  default  is to not trust reverse hostname lookups in this
63          fashion.
64
65       --legacy-uid|-l
66          Traditionally, the kernel has sent only a single uid=  parameter  to
67          the  upcall  for  the  SPNEGO  upcall  that's used to determine what
68          user's credential cache to use.  This parameter is affected  by  the
69          uid=mount  option,  which also governs the ownership of files on the
70          mount.
71
72          Newer kernels send a creduid= option as well,  which  contains  what
73          uid  it  thinks actually owns the credentials that it's looking for.
74          At mount time, this is generally set to the real  uid  of  the  user
75          doing  the  mount. For multisession mounts, it's set to the fsuid of
76          the mount user. Set this option if you want cifs.upcall to  use  the
77          older uid=parameter instead of the creduid= parameter.
78
79       --version|-v
80          Print version number and exit.
81

CONFIGURATION FOR KEYCTL

83       cifs.upcall   is  designed  to  be  called  from  the  kernel  via  the
84       request-key callout program. This requires  that  request-key  be  told
85       where  and  how  to  call this program.  The current cifs.upcallprogram
86       handles two different key types:
87
88       cifs.spnego
89          This keytype is for retrieving kerberos session keys
90
91       dns_resolver
92          This key type is for resolving hostnames into IP addresses.  Support
93          for this key type may eventually be deprecated (see below).
94
95          To  make this program useful for CIFS, you'll need to set up entries
96          for them in request-key.conf(5). Here's an example of an  entry  for
97          each key type:
98
99              #OPERATION  TYPE           D C PROGRAM ARG1 ARG2...
100              #=========  =============  = = ================================
101              create      cifs.spnego    * * /usr/sbin/cifs.upcall %k
102              create      dns_resolver   * * /usr/sbin/cifs.upcall %k
103
104          See request-key.conf(5) for more info on each field.
105
106          The  keyutils package has also started including a dns_resolver han‐
107          dling program as well that is preferred over the one in cifs.upcall.
108          If  you  are  using a keyutils version equal to or greater than 1.5,
109          you should use key.dns_resolver to handle the  dns_resolver  keytype
110          instead of cifs.upcall. See key.dns_resolver(8) for more info.
111

SEE ALSO

113       request-key.conf(5), mount.cifs(8), key.dns_resolver(8)
114

AUTHOR

116       Igor Mammedov wrote the cifs.upcall program.
117
118       Jeff Layton authored this manpage.
119
120       The maintainer of the Linux CIFS VFS is Steve French.
121
122       The  Linux  CIFS  Mailing  list is the preferred place to ask questions
123       regarding these programs.
124
125
126
127
128                                                                CIFS.UPCALL(8)
Impressum