--- name: "k4start" section: "1" platform: "linux" package: "kstart" version: "3.14-1" release: "Debian 5.0 (Lenny)" platforms: ["linux"] url: "https://new.carta.tech/k4start" --- # k4start(1) Obtain and optionally keep active a Kerberos v4 ticket ## NAME k4start - Obtain and optionally keep active a Kerberos v4 ticket ## SYNOPSIS **k4start** \[**-bhnqstv**\] \[**-c** *child pid file*\] \[**-f** *srvtab*\]\ \[**-g** *group*\] \[**-H** *minutes*\] \[**-I** *service instance*\]\ \[**-i** *client instance*\] \[**-K** *minutes*\] \[**-k** *ticket file*\]\ \[**-l** *minutes*\] \[**-m** *mode*\] \[**-o** *owner*\]\ \[**-p** *pid file*\] \[**-r** *service realm*\] \[**-S** *service name*\]\ \[**-u** *client principal*\] \[*username* \[*command* ...\]\] ## DESCRIPTION **k4start** obtains and caches an initial Kerberos v4 ticket-granting ticket for a principal. **k4start** can be used as an alternative to **kinit**, but it is primarily intended to be used by programs that want to use a srvtab to obtain Kerberos credentials, such as a web server that needs to authenticate to another service such as an LDAP server or to AFS. Normally, the principal for which to give tickets should be specified as the first argument. The **-u** and **-i** options can be used as an alternative mechanism for specifying the principal, but generally aren't as convenient. If no username is given as either the first argument or the argument to the **-u** option, the client principal defaults to the Unix username of the user running **k4start** in the default local realm. Optionally, a command may be given on the command line of **k4start**. If so, that command is run after Kerberos authentication (and running **aklog** if desired), with the appropriate environment variables set to point it to the right ticket cache. **k4start** will then continue running, waking up periodically to refresh credentials slightly before they would expire, until the command completes. (The frequency with which it wakes up to refresh credentials can still be controlled with the **-K** option.) To run in this mode, the principal must be specified as a regular command-line argument rather than using the **-u** and **-i** options and a srvtab must be specified with **-f**. The command will not be run using the shell, so if you want to use shell metacharacters in the command with their special meaning, give `"sh -c` *command*`"` as the command to run and quote *command*. If the command contains command-line options (like `"-c"`), put -- on the command line before the beginning of the command to tell **k4start** to not parse those options as its own. When running a command, **k4start** propagates HUP, TERM, and QUIT signals to the child process and does not exit when those signals are received. (If the propagated signal causes the child process to exit, **k4start** will then exit.) This allows **k4start** to react properly when run under a command supervision system such as [*runit*(8)](/runit/8.md) or [*svscan*(8)](/svscan/8.md) that uses signals to control supervised commands. ## OPTIONS - **-b** After starting, detach from the controlling terminal and run in the background. This option only makes sense in combination with **-K** or a command that **k4start** will be running and can only be used if a srvtab is specified with *-f*. **k4start** will not background itself until after it does the initial authentication, so that any initial errors will be reported, but it will then redirect output to */dev/null* and no subsequent errors will be reported. If used in conjunction with a command to run, that command will also run in the background and will also have its input and output redirected to */dev/null*. It will have to report any errors via some other mechanism for the errors to be seen. - **-c** *child pid file* Save the process ID (PID) of the child process into *child pid file*. *child pid file* is created if it doesn't exist and overwritten if it does exist. This option is only allowed when a command was given on the command line and is most useful in conjunction with **-b** to allow management of the running child process. Note that, when used with **-b**, the PID file is written out after **k4start** is backgrounded and changes its working directory to */*, so relative paths for the PID file will be relative to */* (probably not what you want). - **-f** *srvtab* Authenticate using the srvtab *srvtab* rather than asking for a password. - **-g** *group* After creating the ticket cache, change its group ownership to *group*, which may be either the name of a group or a numeric group ID. Ticket caches are created with `0600` permissions by default, so this will have no useful effect unless used with **-m**. If this option is used with a command or with the **-K** option, there may be a short window after each authentication during which the group ownership of the cache will be the default group of the **k4start** process. - **-H** *minutes* Check for a happy ticket, defined as one that has a remaining lifetime of at least *minutes* minutes. If such a ticket is found, do not attempt authentication. Instead, just run the command (if one was specified) or exit immediately with status 0 (if none was). Otherwise, try to obtain a new ticket and then run the command, if any. Cannot be used with **-K**. - **-h** Display a usage message and exit. - **-I** *service instance* The instance portion of the service principal. The default is the default realm of the machine. Note that unlike the client principal, a non-default service principal must be specified with **-I** and **-S**; one cannot provide the instance portion as part of the argument to **-S**. - **-i** *client instance* Specifies the instance portion of the principal. This option doesn't make sense except in combination with **-u**. Note that the instance can be specified as part of *username* through the normal convention of appending a period and then the instance, so one never has to use this option. - **-K** *minutes* Run in daemon mode to keep a ticket alive indefinitely. The program reawakens after *minutes* minutes, checks if the ticket will expire before or less than two minutes after the next wakeup, and gets a new ticket if needed. - **-k** *ticket file* Use *ticket file* as the ticket cache rather than the contents of the environment variable KRBTKFILE or the library default. - **-l** *minutes* Set the ticket lifetime in minutes. Note that if the ticket lifetime will only be accurate to within five minutes, may be approximate if the ticket lifetime is over ten hours, and cannot be more than about 21 hours unless your Kerberos libraries support long ticket lifetimes. - **-m** *mode* After creating the ticket cache, change its file permissions to *mode*, which must be a file mode in octal (`640` or `444`, for example). If this option is used with a command or with the **-K** option, there may be a short window after each authentication during which the file permissions of the ticket cache will be `600`. Setting a *mode* that does not allow **k4start** to read or write to the ticket cache will cause **k4start** to fail and exit when using the **-K** option or running a command. - **-n** Regardless of the setting of the environment variables AKLOG and KINIT\_PROG, don't run the program. - **-o** *owner* After creating the ticket cache, change its ownership to *owner*, which may be either the name of a user or a numeric user ID. If *owner* is the name of a user and **-g** was not also given, also change the group ownership of the ticket cache to the default group for that user. If this option is used with a command or with the **-K** option, there may be a short window after each authentication during which the ownership of the cache will be the user the **k4start** process is running as. - **-p** *pid file* Save the process ID (PID) of the running **k4start** process into *pid* *file*. *pid file* is created if it doesn't exist and overwritten if it does exist. This option is most useful in conjunction with **-b** to allow management of the running **k4start** daemon. Note that, when used with **-b** the PID file is written out after **k4start** is backgrounded and changes its working directory to */*, so relative paths for the PID file will be relative to */* (probably not what you want). - **-q** Quiet. Suppresses the printing of the initial banner message saying what Kerberos principal tickets are being obtained for, and also suppresses the password prompt when the **-s** option is given. - **-r** *service realm* The realm for the service principal. This defaults to the default local realm. - **-S** *service name* Specifies the principal for which **k4start** is getting a service ticket. The default value is `"krbtgt"`, to obtain a ticket-granting ticket. This option (along with **-I**) may be used if one only needs access to a single service. Note that unlike the client principal, a non-default service principal must be specified with both **-S** and **-I**; one cannot provide the instance portion as part of the argument to **-S**. - **-s** Read the password from standard input. This bypasses the normal password prompt, which means echo isn't suppressed and input isn't forced to be from the controlling terminal. Most uses of this option are a security risk. You normally want to use a srvtab and the **-f** option instead. - **-t** Run an external program after getting a TGT. The default use of this is to run **aklog** to get a token. If the environment variable KINIT\_PROG is set, the program is run regardless of the **-t** flag (unless the **-n** flag is given). If **k4start** has been built with AFS *setpag()* support and a command was given on the command line, **k4start** will create a new PAG before obtaining AFS tokens. Otherwise, it will obtain tokens in the current PAG. - **-u** *client principal* This specifies the principal to obtain credentials as. The entire principal may be specified here, or alternatively just the first portion may be specified with this flag and the instance specified with **-i**. Note that there's normally no reason to use this flag rather than simply giving the principal on the command line as the first regular argument. - **-v** Be verbose. This will print out a bit of additional information about what is being attempted and what the results are. ## RETURN VALUES The program exits with status 0 if it successfully gets a ticket or has a happy ticket (see **-H**). If **k4start** runs aklog or some other program **k4start** returns the exit status of that program. ## EXAMPLES Use the */etc/srvtab* srvtab to obtain a ticket granting ticket for the principal `"rcmd.example"`, putting the ticket cache in */tmp/service.tgt*. The lifetime is 600 minutes and the program wakes up every 10 minutes to check if the ticket is about to expire. ``` k4start -k /tmp/service.tgt -f /etc/srvtab -K 10 -l 600 \ rcmd.example ``` Do the same, but using the default ticket cache and run the command /usr/local/bin/auth-backup. **k4start** will continue running until the command finishes. ``` k4start -f /etc/srvtab -K 10 -l 600 rcmd.example \ /usr/local/bin/auth-backup ``` Shows the permissions of the temporary cache file created by **k4start**: ``` k4start -f /etc/srvtab rcmd.example \ -- sh -c 'ls -l $KRBTKFILE' ``` Notice the `"--"` before the command to keep **k4start** from parsing the `"-c"` as its own option. Starts **k4start** as a daemon using the Debian **start-stop-daemon** management program. This is the sort of line that one could put into a Debian init script: ``` start-stop-daemon --start --pidfile /var/run/k4start.pid \ --exec /usr/local/bin/k4start -- -b -p /var/run/k4start.pid \ -f /etc/srvtab rcmd.example ``` This uses */var/run/k4start.pid* as the PID file and obtains `"rcmd.example"` tickets from the system srvtab file. **k4start** would then be stopped with: ``` start-stop-daemon --stop --pidfile /var/run/k4start.pid rm -f /var/run/k4start.pid ``` This code could be added to an init script for Apache, for example, to start a **k4start** process alongside Apache to manage its Kerberos credentials. ## ENVIRONMENT If the environment variable AKLOG is set, its value will be taken as the path to a program and that program will be automatically executed after the ticket-granting ticket has been retrieved (unless **-n** was given). If AKLOG is not set and KINIT\_PROG is set, its value will be used instead. KINIT\_PROG is honored for backward compatibility but its use is not recommended due to its confusing name. If no ticket file (with **-k**) or command is specified on the command line, **k4start** will use the environment variable KRBTKFILE to determine the location of the the ticket granting ticket. If either a command is specified or the **-k** option is used, KRBTKFILE will be set to point to that file before running the **aklog** program or any command given on the command line. ## FILES The default ticket cache is determined by the underlying Kerberos libraries. The default path for aklog is determined at build time, and will normally be whichever of **aklog** or **afslog** is found in the user's path. If a command is specified and **-k** was not given, **k4start** will create a temporary ticket cache file of the form `"/tmp/tkt%d_%s"` where `%d` is the UID **k4start** is running as and `%s` is a random string. ## SEE ALSO [*k5start*(1)](/k5start/1.md), [*kinit*(1)](/kinit/1.md), [*krenew*(1)](/krenew/1.md) The kstart web page at \ will have the current version of **k4start**, **k5start**, and **krenew**. ## AUTHORS **k4start** was originally written by Robert Morgan. Modifications and additional features were added by Booker C. Bense. Additional cleanup and current maintenance are done by Russ Allbery \. Implementations of **-b** and **-p** and the example for a Debian init script are based on code contributed by Navid Golpayegani.