manpagez: man pages & more
man ncctl(1)
Home | html | info | man

ncctl(1)                  BSD General Commands Manual                 ncctl(1)


     ncctl -- Control NFS kernel credentials


     ncctl [-Pvh] {{init | set} [-F] -p principal | {destroy | unset} |
           {list | get}} [path ...]
     ncinit [-PvhF] -p principal [path ...]
     ncdestroy [-Pvh] [path ...]
     nclist [-Pvh] [path ...]


     ncctl controls the caller's kernel Kerberos credentials for any of the
     specified path's associated NFS mounts.  If no paths are specified then
     all the caller's associated credentials for all NFS file systems are
     acted upon by the command given.

     When an NFS file system is mounted using Kerberos through the ``sec=''
     option or by the export specified on the server, the resulting session
     context is stored in a table for each mount. If the user decides to fin-
     ish his or her session or chooses to use a different credential, then
     ncctl can be called to invalidate or change those credentials in the ker-

     ncctl supports the following commands:

     init, set        Set the mount or mounts to obtain credentials form the
                      associated principal. Any current credential is unset.

     destroy, unset   Unset the current credentials on the mount or mounts.

     list, get        List the principal(s) set on the mount or mounts for
                      this session. If no principal was set, then display
                      ``Default credential'' followed by ``[from <principal
                      name>]'' if the access succeeded and ``[kinit needed]''
                      if not.  If there has been no access to the file system
                      then display ``Credentials are not set''.

     Note the second synopsis is equivalent to
             ncctl [-Pv] {init | set} [-F] -p principal
     The third synopsis is equivalent to
             ncctl [-Pv] {destroy | unset}
     And the last synopsis is equivalent to
             ncctl [-Pv] {list | get}

     Kerberos keeps a collection of credentials which can be seen by using

           klist -A.

     The current default credential can be seen with klist without any argu-
     ments.  kswitch can be used to switch the default to a different Kerberos
     credential.  kdestroy can be use to remove all or a particular Kerberos
     credential.  New Kerberos credentials can be obtain and added to the col-
     lection by calling kinit and those credentials can be used when accessing
     the mount.  See kinit(1), klist(1), kswitch(1), and kdestroy(1).

     ncctl can set any principal from the associated Kerberos credentials or
     can destroy and unset credentials currently on the mount. When accessing
     a Kerberos mounted NFS file system, if no principal is set on the mount,
     when the kernel needs credentials it will make an up call to the gssd
     daemon and what ever the default credentials are available at the time
     will be used.

     The options are as follows:

     -h, --help       Print a help summary of the command and then exit.

     -v, --verbose    Be verbose and show what file system is being operated
                      on and any resulting errors.

     -P, --nofollow   If the trailing component resolves to a symbolic link do
                      not resolve the link but use the current path to deter-
                      mine any associate NFS file system.

     -p, --principal <principal>
                      For the init, set and ncinit commands set the principal
                      to <principal>.  This option is required for theses com-
                      mands. This option is not valid for other commands.

     -F, --force      For the init, set and ncinit commands to not check the
                      presence of the required principal in the Kerberos cache
                      collection.  This may be useful if Kerberos credentials
                      will be obtain later.
                      WARNING: If the credential is incorrectly set it may not
                      work  and  no  access  to  the  file system will ever be
                      allowed until  another  set  or  unset  operation  takes
                      place.  This option is not valid for other commands.


     If leaving for the day:

      $ kdestroy -A
      $ ncdestroy

     Lets say a user does

      $ kinit user@FOO.COM

     And through the automounter access a path /Network/Serves/some-
     server/Sources/foo/bar where the mount of /Network/Servers/some-
     server/Sources/foo was done with user@FOO.COM.

      $ cat /Network/Servers/someserver/Sources/foo/bar
      cat: /Network/Servers/someserver/Sources/foo/bar: Permission denied

     The user realizes that in order to have access on the server his identity
     should be user2@BAR.COM. So:

      $ kinit user2@BAR.COM
      $ ncctl set -p user2@BAR.COM

     Now the local user can access bar. To see your credentials

     $ nclist
     /Network/Servers/someserver/Sources/foo: user2@BAR.COM

     If the user destroys his credentials and then acquires new ones

     $ ncdestroy
     $ nclist -v
     /private/tmp/mp                    : No credentials are set.
     /Network/Servers/xs1/release       : NFS mount is not using Kerberos.
     $ kinit user
     user@FOO.COM's password: ******
     $ klist
     Credentials cache: API:648E3003-0A6B-4BB3-8447-1D5034F98EAE
             Principal: user@FOO.COM

       Issued                Expires               Principal
     Dec 15 13:57:57 2014  Dec 15 23:57:57 2014  krbtgt/FOO.COM@FOO.COM
     $ ls /private/tmp/mp
     filesystemui.socket=    sysdiagnose.tar.gz      x
     mtrecorder/             systemstats/            z
     $ nclist
     /private/tmp/mp                 : Default credential [from user@FOO.COM]


     As mentioned above credentials are per session, so the console session's
     credential cache collection is separate for a collections of credentials
     obtain in an ssh session even by the same user.  Kerberos will set the
     default credential with klist or kswitch.  However, the default creden-
     tial can change without the user's knowledge, because of renewals or some
     other script or program in the user's session is run and does a kswitch
     (krb5_cc_set_default_name()) or kinit on the user's behalf.  kinit may
     not prompt for a password if the Kerberos password for the principal is
     in the user's keychain.

     ncctl with the set command will allow a user to change the mapping of the
     local user identity to a different one on the server. It is up to the
     user to decide which identity will be used.

     Previous versions of gssd daemon would attempt to select credentials if
     they were not set, by choosing credentials in the same realm as the
     server. This was imperfect and that has been removed. There may be multi-
     ple credentials in the same realm or a user may prefer a cross realm
     principal. It is highly recommended that after accessing a mount (typi-
     cally through the automounter) that if the user has access to multiple
     credentials to set the credential on the mount that they want to use. The
     current default credential will be used by the automounter on first
     mount. If you do not explicitly set the credentials to use, then if the
     server expires the credential, the client will use the current default
     credential at the time of renewal and that may be a different identity.

     If using mount directly a user can select what credential to use for the
     mount and subsequently there after (at least until a new ncctl set com-
     mand is run) by using the principal=<principal> option. It is also possi-
     ble to select the realm to use with the realm=<realm> option. The latter
     can be useful to administrators in automounter maps.

     There is currently no way to remember what the chosen identity is for a
     given mount after its been unmounted. So for automounted mounts a refer-
     ence it taken on the mount point so unmounts will not happen until all
     credentials on a mount with a set principal have been destroyed. Forced
     unmounts will not be effected.  nclist or ncctl get can be used to see
     what credentials are actually being used and ncdestroy or unset can be
     used to destroy that session's credential. Accessing the mount after its
     credentials have been destroyed will cause the default credential to be
     used until the next ncinit or ncctl set Default credentials for an auto-
     mounted NFS mount will not prevent the unmounting of the file system.


     The ncctl command will exit with 1 if any of the supplied paths doesn't
     exist or there is an error returned for any path tried. If all paths
     exist and no errors are returned the exit status will be 0.


     kdestroy(1), kinit(1), klist(1), kswitch(1), mount_nfs(8)


     There should be an option to kdestroy to destroy cached NFS contexts.

BSD                            January 14, 2015                            BSD

Mac OS X 10.11.6 - Generated Thu Feb 2 19:01:50 CST 2017
© 2000-2021
Individual documents may contain additional copyright information.