diff options
Diffstat (limited to 'cifs.upcall.rst.in')
| -rw-r--r-- | cifs.upcall.rst.in | 190 |
1 files changed, 190 insertions, 0 deletions
diff --git a/cifs.upcall.rst.in b/cifs.upcall.rst.in new file mode 100644 index 0000000..8f4ee62 --- /dev/null +++ b/cifs.upcall.rst.in @@ -0,0 +1,190 @@ +=========== +cifs.upcall +=========== + +-------------------------------------------------------------- +Userspace upcall helper for Common Internet File System (CIFS) +-------------------------------------------------------------- +:Manual section: 8 + + +******** +SYNOPSIS +******** + +.. code-block:: perl + + cifs.upcall [--trust-dns|-t] [--version|-v] [--legacy-uid|-l] + [--krb5conf=/path/to/krb5.conf|-k /path/to/krb5.conf] + [--keytab=/path/to/keytab|-K /path/to/keytab] {keyid} + + + +*********** +DESCRIPTION +*********** + + +This tool is part of the cifs-utils suite. + +\ **cifs.upcall**\ is a userspace helper program for the linux CIFS client +filesystem. There are a number of activities that the kernel cannot +easily do itself. This program is a callout program that does these +things for the kernel and then returns the result. + +\ **cifs.upcall**\ is generally intended to be run when the kernel calls +request-key(8) for a particular key type. While it can be run +directly from the command-line, it's not generally intended to be run +that way. + + +******* +OPTIONS +******* + + + +\ **-c**\ + + This option is deprecated and is currently ignored. + + + +\ **--no-env-probe|-E**\ + + Normally, \ **cifs.upcall**\ will probe the environment variable space of + the process that initiated the upcall in order to fetch the value of + \ ``$KRB5CCNAME``\ . This can assist the program with finding credential + caches in non-default locations. If this option is set, then the + program won't do this and will rely on finding credcaches in the + default locations specified in \ *krb5.conf*\ . Note that this is never + performed when the uid is 0. The default credcache location is always + used when the uid is 0, regardless of the environment variable setting + in the process. + + + +\ **--krb5conf|-k=/path/to/krb5.conf**\ + + This option allows administrators to set an alternate location for the + \ *krb5.conf*\ file that \ **cifs.upcall**\ will use. + + + +\ **--keytab=|-K=/path/to/keytab**\ + + This option allows administrators to specify a keytab file to be + used. When a user has no credential cache already established, + \ **cifs.upcall**\ will attempt to use this keytab to acquire them. The + default is the system-wide keytab \ */etc/krb5.keytab*\ . + + + +\ **--trust-dns|-t**\ + + With krb5 upcalls, the name used as the host portion of the service + principal defaults to the hostname portion of the UNC. This option + allows the upcall program to reverse resolve the network address of + the server in order to get the hostname. + + This is less secure than not trusting DNS. When using this option, + it's possible that an attacker could get control of DNS and trick the + client into mounting a different server altogether. It's preferable to + instead add server principals to the KDC for every possible hostname, + but this option exists for cases where that isn't possible. The + default is to not trust reverse hostname lookups in this fashion. + + + +\ **--legacy-uid|-l**\ + + Traditionally, the kernel has sent only a single uid= parameter to the + upcall for the SPNEGO upcall that's used to determine what user's + credential cache to use. This parameter is affected by the \ **uid=**\ + mount option, which also governs the ownership of files on the mount. + + Newer kernels send a creduid= option as well, which contains what uid + it thinks actually owns the credentials that it's looking for. At + mount time, this is generally set to the real uid of the user doing + the mount. For multisession mounts, it's set to the fsuid of the mount + user. Set this option if you want cifs.upcall to use the older \ **uid=**\ + parameter instead of the creduid= parameter. + + + +\ **--version|-v**\ + + Print version number and exit. + + + + +************************ +CONFIGURATION FOR KEYCTL +************************ + + +\ **cifs.upcall**\ is designed to be called from the kernel via the +request-key callout program. This requires that request-key be told +where and how to call this program. The current \ **cifs.upcall**\ +program handles two different key types: + + +\ **cifs.spnego**\ + + This keytype is for retrieving kerberos session keys + + + +\ **dns_resolver**\ + + This key type is for resolving hostnames into IP addresses. Support + for this key type may eventually be deprecated (see below). + + To make this program useful for CIFS, you'll need to set up entries + for them in request-key.conf(5). Here's an example of an entry for + each key type: + + + .. code-block:: perl + + #OPERATION TYPE D C PROGRAM ARG1 ARG2... + #========= ============= = = ================================ + create cifs.spnego * * @sbindir@/cifs.upcall %k + create dns_resolver * * @sbindir@/cifs.upcall %k + + + See request-key.conf(5) for more info on each field. + + The keyutils package has also started including a dns_resolver + handling program as well that is preferred over the one in + \ **cifs.upcall.**\ If you are using a keyutils version equal to or + greater than 1.5, you should use \ ``key.dns_resolver``\ to handle the + \ ``dns_resolver``\ keytype instead of \ **cifs.upcall**\ . See + key.dns_resolver(8) for more info. + + + + +******** +SEE ALSO +******** + + +request-key.conf(5), mount.cifs(8), key.dns_resolver(8) + + +****** +AUTHOR +****** + + +Igor Mammedov wrote the cifs.upcall program. + +Jeff Layton authored this manpage. + +The maintainer of the Linux CIFS VFS is Steve French. + +The Linux CIFS Mailing list is the preferred place to ask questions +regarding these programs. + |