1KRENEW(1) User commands KRENEW(1)
2
6 krenew - Renew a Kerberos v5 ticket
7
9 krenew [-bhtv] [-c child pid file] [-H minutes]
10 [-K minutes] [-k ticket file] [-p pid file]
11 [command ...]
12
14 krenew renews an existing renewable ticket. When run without any argu‐
15 ments, it just attempts to renew the existing ticket-granting ticket in
16 the current ticket cache, equivalent to "kinit -R", but it can option‐
17 ally run a program like aklog to refresh AFS tokens, can run as a dae‐
18 mon and wake up periodically to renew the ticket cache, or can run a
19 specified command and keep renewing the ticket cache until the command
20 finishes (or renewal is no longer possible). If a command is speci‐
21 fied, krenew by default wakes up every 60 minutes (1 hour) to check the
22 ticket cache.
23 If a command is given, it will not be run using the shell, so if you
25 want to use shell metacharacters in the command with their special
26 meaning, give "sh -c command" as the command to run and quote command.
27 If the command contains command-line options (like "-c"), put -- on the
28 command line before the beginning of the command to tell krenew to not
29 parse those options as its own.
30 If krenew is built with setpag support and AFS tokens are requested
32 with the -t option, it will put the command in a separate PAG before
33 obtaining AFS tokens so that they don't interfere with other processes
34 on the system.
35 When running a command, krenew propagates HUP, TERM, and QUIT signals
37 to the child process and does not exit when those signals are received.
38 (If the propagated signal causes the child process to exit, krenew will
39 then exit.) This allows krenew to react properly when run under a com‐
40 mand supervision system such as runit(8) or svscan(8) that uses signals
41 to control supervised commands.
42
44 -b After starting, detach from the controlling terminal and run in the
45 background. This option only makes sense in combination with -K or
46 a command that krenew will be running. krenew will not background
47 itself until after it does the initial ticket renewal, so that any
48 initial errors will be reported, but it will then redirect output
49 to /dev/null and no subsequent errors will be reported.
50 If used in conjunction with a command to run, that command will
52 also run in the background and will also have its input and output
53 redirected to /dev/null. It will have to report any errors via
54 some other mechanism for the errors to be seen.
55 Use of this flag on Mac OS X without specifying a file-based ticket
57 cache by either using -k or setting KRB5CCNAME will probably not do
58 what you want. Ticket caches on Mac OS X are, by default, per-ses‐
59 sion and with -b krenew will detach itself from your existing
60 ticket cache. Instead, to renew the default ticket cache on Mac OS
61 X, try something like:
62 (krenew -K 60 &)
64 to run krenew in the background but within the current session.
66 -c child pid file
68 Save the process ID (PID) of the child process into child pid file.
69 child pid file is created if it doesn't exist and overwritten if it
70 does exist. This option is only allowed when a command was given
71 on the command line and is most useful in conjunction with -b to
72 allow management of the running child process.
73 Note that, when used with -b, the PID file is written out after
75 k4start is backgrounded and changes its working directory to /, so
76 relative paths for the PID file will be relative to / (probably not
77 what you want).
78 -H minutes
80 Only renew the ticket if it has a remaining lifetime of less than
81 minutes minutes. If either the ticket already has a sufficiently
82 long remaining lifetime or renewal was successful, run the command
83 (if one was specified) or exit immediately with status 0 (if none
84 was). Otherwise, try to renew the ticket so that it will have a
85 remaining lifetime of at least minutes, exit with an error if
86 unsuccessful, and then run the command, if any. Cannot be used
87 with -K.
88 -h Display a usage message and exit.
90 -K minutes
92 Run in daemon mode to keep a ticket alive indefinitely. The pro‐
93 gram reawakens after minutes minutes, checks if the ticket will
94 expire before the next wakeup, and renews the ticket if needed. If
95 this option is not given but a command was given on the command
96 line, the default interval is 60 minutes (1 hour).
97 -k ticket file
99 Use ticket file as the ticket cache rather than the contents of the
100 environment variable KRB5CCNAME or the library default. ticket
101 file should be the path to a file, without any leading "FILE:"
102 string. Using this option forces a file-based ticket cache; if you
103 wish to use a different type of ticket cache, don't specify -k and
104 instead set KRB5CCNAME to the designator of the cache you wish to
105 use.
106 -p pid file
108 Save the process ID (PID) of the running krenew process into pid
109 file. pid file is created if it doesn't exist and overwritten if
110 it does exist. This option is most useful in conjunction with -b
111 to allow management of the running krenew daemon.
112 Note that, when used with -b the PID file is written out after kre‐
114 new is backgrounded and changes its working directory to /, so rel‐
115 ative paths for the PID file will be relative to / (probably not
116 what you want).
117 -t Run an external program after getting a ticket. The default use of
119 this is to run aklog to get a token. If the environment variable
120 KINIT_PROG is set, it overrides the compiled-in default.
121 If krenew has been built with AFS setpag support and a command was
123 given on the command line, krenew will create a new PAG before
124 obtaining AFS tokens. Otherwise, it will obtain tokens in the cur‐
125 rent PAG.
126 -v Be verbose. This will print out a bit of additional information
128 about what is being attempted and what the results are.
129
131 The program normally exits with status 0 if it successfully renews a
132 ticket. If krenew runs aklog or some other program krenew returns the
133 exit status of that program.
134
136 Renew the current ticket-granting ticket.
137 krenew
139 Wake up every ten minutes and check to see if the ticket cache needs
141 renewing. If it does, re-run aklog as well.
142 krenew -K 10 -t
144 Run the program /usr/local/bin/compute-job in the background, checking
146 every hour to see if the ticket needs to be renewed (the default). Put
147 the PID of the krenew job in /var/run/compute.pid. Obtain a new AFS
148 token each time the ticket has to be renewed.
149 krenew -b -t -p /var/run/compute.pid /usr/local/bin/compute-job
151 If you wanted to pass options to /usr/local/bin/compute-job, putting a
153 "--" argument before it would be necessary to keep krenew from inter‐
154 preting those options as its own.
155 If you want to redirect output to a file that requires authentication
157 to write to, you will need to do that redirection in a subshell. In
158 other words, the following command:
159 krenew -t compute-job > /afs/local/data/output
161 won't work if /afs/local/data/output requires an AFS token to write to.
163 The job, while running, will have an AFS token, but the output redi‐
164 rection is done in the parent shell and doesn't benefit from krenew.
165 The above should instead be written as:
166 krenew -t -- sh -c 'compute-job > /afs/local/data/output'
168 With this command, the shell doing the redirection will also be run
170 under krenew and have the benefit of the AFS token it obtains.
171
173 If the environment variable KINIT_PROG is set to a program (such as
174 aklog) then this path will be used for the program to run with -t
175 rather than the default compiled into krenew.
176 If no ticket file (with -k) or command is specified on the command
178 line, krenew will use the environment variable KRB5CCNAME to determine
179 the location of the the ticket granting ticket. If the -k option is
180 used, KRB5CCNAME will be set to point to the ticket file before running
181 the aklog program or any command given on the command line.
182
184 The default ticket cache is determined by the underlying Kerberos
185 libraries. The default path for aklog is determined at build time, and
186 will normally be whichever of aklog or afslog is found in the user's
187 path.
188
190 k5start(1), kinit(1)
191 The kstart web page at <http://www.eyrie.org/~eagle/software/kstart/>
193 will have the current version of krenew.
194
196 krenew was written by Russ Allbery <rra@stanford.edu>. It was based
197 heavily on k5start by Booker C. Bense, which in turn was based on the
198 k4start code written by Robert Morgan.
1993.11 2008-04-09 KRENEW(1)