diff options
Diffstat (limited to 'cifs.upcall.rst.in')
| -rw-r--r-- | cifs.upcall.rst.in | 200 |
1 files changed, 76 insertions, 124 deletions
diff --git a/cifs.upcall.rst.in b/cifs.upcall.rst.in index 8f4ee62..1b8df3f 100644 --- a/cifs.upcall.rst.in +++ b/cifs.upcall.rst.in @@ -7,178 +7,131 @@ 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} - - + 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 +``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 +``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. - - - +-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 +``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**\ +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:: -\ **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 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. @@ -187,4 +140,3 @@ 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. - |