ncctl
NCCTL(1) General Commands Manual NCCTL(1)
NAME
ncctl – Control NFS kernel credentials
SYNOPSIS
ncctl [-Pvh] {{init | set} [-F] -p principal | {destroy | unset} |
{list | get}} [path ...]
ncinit [-PvhF] -p principal [path ...]
ncdestroy [-Pvh] [path ...]
nclist [-Pvh] [path ...]
DESCRIPTION
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 finish his or her
session or chooses to use a different credential, then ncctl can be called
to invalidate or change those credentials in the kernel.
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
arguments. 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 collection 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 determine
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 commands.
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.
EXAMPLES
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/someserver/Sources/foo/bar where the mount of
/Network/Servers/someserver/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]
NOTES
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 credential
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 multiple
credentials in the same realm or a user may prefer a cross realm principal.
It is highly recommended that after accessing a mount (typically 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 command
is run) by using the principal=⟨principal⟩ option. It is also possible 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 reference
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 ncctl 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
automounted NFS mount will not prevent the unmounting of the file system.
DIAGNOSTICS
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.
SEE ALSO
kdestroy(1), kinit(1), klist(1), kswitch(1), mount_nfs(8)
BUGS
There should be an option to kdestroy to destroy cached NFS contexts.
macOS 12.1 January 14, 2015 macOS 12.1