diff options
Diffstat (limited to 'svc/man')
| -rw-r--r-- | svc/man/init | 655 |
1 files changed, 655 insertions, 0 deletions
diff --git a/svc/man/init b/svc/man/init new file mode 100644 index 0000000..1646649 --- /dev/null +++ b/svc/man/init @@ -0,0 +1,655 @@ +.TH INIT +.SH NAME +init, svc, halt, shutdown, reboot, reset \- run and control services +.SH SYNOPSIS +.B init +[ +.B -d +.I svcdir +] [ +.B -l +.I logdir +] [ +.B -m +.I mtpt +] [ +.B -s +.I srvname +] +.PP +.B svc +[ +.I cmd +[ +.I name ... +]] +.PP +.B halt +.br +.B shutdown +.br +.B reboot +.br +.B reset +.SH DESCRIPTION +.I Init +runs the services described in +.BR /lib/svc . +It is not tied to booting; see +.B AS SYSINIT +below. +.PP +To interact with services, mount the filesystem +.I init +serves: +.PP +.EX +mount /srv/svc /mnt/svcs +.EE +.PP +This is optional. Services run whether or not anyone ever mounts it, and if +.I init +cannot post the filesystem it says so and carries on supervising. The control +plane is for people, not for the machine. +.PP +Options are: +.TP +.BI -d " svcdir" +Read service definitions from +.I svcdir +instead of +.BR /lib/svc . +.TP +.BI -l " logdir" +Write service output to +.I logdir +instead of +.BR /log . +.TP +.BI -m " mtpt" +Mount at +.I mtpt +instead of +.BR /mnt/svcs . +.TP +.BI -s " srvname" +Post at +.BI /srv/ srvname +instead of +.BR /srv/svc . +.PP +Every path is an option because +.I init +must be runnable as an ordinary process for testing. See +.B TESTING +below. +.SH CONFIGURATION IS FILES +.I Init +never writes +.BR /lib/svc . +Everything about how a service is configured, including whether it starts at +boot, is in its file and is changed by editing that file. The filesystem +described below accepts commands about what is running now; it does not accept +configuration, and there is no exception to this. +.PP +The consequence worth knowing before it surprises you: +.B stop +does not survive a reboot. To stop a service from starting at boot, set +.B enable=no +in its file. To act on an edit without rebooting, use +.BR reload . +.SH COMMANDS +These are small programs that open a file and write a word to it. Anything they +do can be done by hand; see +.B THE SERVICE FILESYSTEM +below. +.TP +.B svc +With no arguments, print every service, its state, and why it is in that state, +in aligned columns. +.TP +.BI svc " cmd name ..." +.I Cmd +is +.BR start , +.BR stop , +.BR restart , +.BR status , +or +.BR log . +.B Svc log +prints what the service has written and then keeps printing as it writes more, +until interrupted. +.TP +.B halt +Stop all services, halt the file server, and power off. +.B Shutdown +is another name for it. +.TP +.B reboot +As +.BR halt , +but restart the kernel. +.TP +.B reset +Stop all services and start them again. The kernel keeps running and the file +server is not halted. +.PP +To make this machine an authentication server, put +.B enable=yes +in the +.B keyfs +and +.B authsrv +files and then: +.PP +.EX +svc reload +svc start keyfs authsrv +.EE +.SH THE SERVICE FILESYSTEM +.EX +/mnt/svcs/ + ctl control everything + status state of every service + <name>/ + ctl control one service + status state of one service + args command line + env environment + ns namespace in effect + user identity it runs as + log output + pid +.EE +.PP +Every file except the two +.B ctl +files is read-only. Configuration is changed by editing +.BR /lib/svc , +never here. +.PP +Which file you write to says how far a command reaches. The two +.B ctl +files accept: +.PP +.EX + /mnt/svcs/ctl /mnt/svcs/<name>/ctl +start start <name> start +stop stop <name> stop +restart restart <name> restart +note - note <string> +reload reload - +reexec reexec - +halt reboot reset yes - +.EE +.PP +.B Start +and +.B stop +affect only what is running now. +.B Note +posts a note to the service's process. +.B Reload +re-reads +.BR /lib/svc . +.B Reexec +replaces +.I init +with a new +.I init +binary without stopping services or rebooting. +.PP +Reading a +.B ctl +file lists the commands it accepts, so you never have to guess or read source: +.PP +.EX +% cat /mnt/svcs/dns/ctl +start +stop +restart +note <string> post a note to the process +.EE +.PP +A write that is not understood fails and names the alternatives: +.PP +.EX +% echo frobnicate >/mnt/svcs/ctl +echo: write error: unknown command "frobnicate"; try + halt reboot reset start stop restart reload reexec +.EE +.PP +.B Status +is in +.I ndb +format rather than columns, so that fields can be added without breaking +anything that reads it, and so that an exit message containing blanks needs no +special case: +.PP +.EX +% cat /mnt/svcs/status +svc=dns state=running pid=231 enable=yes +svc=authsrv state=failed restarts=3 exit='cannot open /adm/keys' +svc=listen state=waiting needs=cs +svc=ipconf state=done +.EE +.PP +The states are: +.TF starting +.TP +.B stopped +Not running, and not trying to be. +.TP +.B waiting +Wants to run, but something in its +.B needs +has not come up yet. The +.B needs +attribute in +.B status +says which. +.TP +.B starting +Started, but not yet up according to its +.B ready +attribute. +.TP +.B running +Up. +.TP +.B done +A +.B ready=exit +service that finished successfully. It is not running and will not be started +again. +.TP +.B failed +Gave up. The +.B exit +attribute says why. +.PP +.B Pid +is empty for a service that has no process of its own: a +.B ready=srv: +service whose process has exited by design, or one that has finished or not +started. +.PP +Permissions are ordinary file permissions, checked by +.I init +against the identity of whoever attached, so the same rules apply to a local +write and to a remote mount. By default the global +.B ctl +is writable only by the host owner, and a service's own +.B ctl +is writable by the host owner and by the user the service runs as. Note that if +.B /srv/svc +is exported, anyone who can mount it can halt the machine. +.SH SERVICE FILES +Each file in +.B /lib/svc +describes one service, in +.I ndb +format. +.PP +.EX +svc=dns + exec=/bin/ndb/dns + args=-r + needs=cs + ready=srv:dns + restart=always + enable=yes +.EE +.PP +The attributes are: +.TF restart +.TP +.B svc +The name. Must match the file name. +.TP +.B exec +Program to run. Required unless +.B adopt=yes +is set. +.TP +.B args +An argument. May be repeated, and repeated attributes are passed in the order +they appear in the file. +.TP +.B env +A +.IB name = value +pair for the environment. May be repeated. +.TP +.B needs +Another service that must come up first. May be repeated. A dependency is +satisfied when it reaches +.B running +or +.BR done . +This is ordering only: if a dependency later fails or is restarted, nothing +happens to the services that named it. Cycles are reported by +.BR reload . +.TP +.B ready +How to tell the service has come up, and for one form, how to tell it is still +up. See +.B KINDS OF SERVICE +below. +.TP +.B restart +.BR never , +.B onfail +(the default: restart only on a non-empty exit status), or +.BR always . +What is watched depends on +.BR ready , +so see +.B KINDS OF SERVICE +before setting this. +.TP +.B stop +How to stop it, when a +.B hangup +note will not do. One of: +.RS +.TP +.BI note: string +Post +.I string +as a note. The default is +.BR note:hangup . +.TP +.IB write: file : word +Write +.I word +to +.IR file . +This is how a file server that shuts down on a command to its +.B /srv +file says so, for example +.BR write:/srv/hjfs.cmd:halt . +.TP +.BI exec: cmd +Run +.IR cmd . +.RE +.TP +.B adopt +.B yes +for a service +.I init +did not start and cannot start: it has no +.BR exec , +.I init +is not its parent, and it can only be stopped. The root file server is the +case this exists for. An adopted service needs a +.B ready +attribute so that +.I init +can tell whether it is there, and a +.B stop +attribute so that +.I init +can shut it down. +.TP +.B ns +A namespace file, in the format of +.IR namespace . +.TP +.B user +The identity to run as. +.TP +.B enable +.B yes +to start at boot. Only a person writes this; +.I init +never does. +.PP +An attribute that is not in this list is an error. Nothing here is a hint: +.B exce=/bin/ndb/dns +is valid ndb and means nothing, so ignoring unknown attributes would let a typo +do nothing quietly forever. +.PP +There is nothing else to set. The times involved are fixed: a service gets 30 +seconds to become ready, 5 seconds to stop before it is killed, and 1 second +between restarts; a service that restarts more than 5 times in 60 seconds is +marked +.BR failed . +These are constants until something demonstrates they need to be otherwise. +.PP +.B Reload +applies every file that parses and leaves the rest alone, so one bad file never +costs you the machine. The write fails with a summary, and each service that +could not be loaded says why in its own +.BR status : +.PP +.EX +% echo reload >/mnt/svcs/ctl +echo: write error: 2 of 14 service files rejected; see status +% grep 'state=failed' /mnt/svcs/status +svc=dns state=failed exit='/lib/svc/dns:4: unknown attribute "exce"' +.EE +.SH KINDS OF SERVICE +Not everything stays in the foreground, and +.I init +does not guess. The +.B ready +attribute says how to tell a service came up, and in one case what to watch +afterwards. +.TF srv:name +.TP +.B exec +It stays in the foreground and is up as soon as it is started. Its process is +watched, and +.B restart +applies to that process exiting. This is the default. +.TP +.BI srv: name +It is up once +.BI /srv/ name +exists. Use this for a service that posts to +.B /srv +and lets the process you started exit, which many Plan 9 file servers do on +purpose. For these the +.B /srv +file is watched and the process is not, so the process exiting is normal and +never causes a restart; +.B restart +applies to the +.B /srv +file going away. +.TP +.BI dial: addr +It is up once a dial of +.I addr +succeeds. This is a readiness test only: the process is still what is watched +afterwards, exactly as for +.BR exec , +and +.I init +does not keep dialling. +.TP +.B exit +It runs once and finishes; it is not a daemon. Use this for setup that has to +happen before something else starts. It reaches +.B done +rather than +.BR running , +it satisfies +.B needs +by doing so, and it is never restarted \- a +.B restart +attribute on it is an error rather than something quietly ignored. +.SH NAMESPACE AND USER +Each service runs in its own namespace group. If it has an +.B ns +attribute that namespace is built from the named file; otherwise it inherits the +namespace +.I init +is using. This is what lets two services on one machine hold entirely different +views of the filesystem \- a different +.BR /net , +a different +.BR /srv , +a different +.B /mnt/factotum +and so different keys and a different identity. +.PP +Because a service has its own namespace, a service that runs +.I bind +changes nothing for anyone else. Services use namespaces; they do not build the +shared one. The namespace everything starts from is built by +.I init +before any service runs. +.PP +A service with a +.B user +attribute is run under that identity using the capability device, since Plan 9 +has no setuid. This requires +.I init +to be running as the host owner; an +.I init +that is not cannot honour +.B user +and fails any service that asks for one, rather than silently running it as the +wrong identity. +.SH STARTING AND STOPPING +Services marked +.B enable=yes +are started in dependency order, each waiting for the ones it +.B needs +to reach +.B running +or +.BR done . +.PP +They are stopped in the reverse of that order. Each is stopped the way its +.B stop +attribute says, or by a +.B hangup +note; if it has not gone after 5 seconds it is killed. A stuck service never +holds up the rest. +.SH AS SYSINIT +Nothing above depends on how +.I init +was started. An instance can be run by anyone, over any directory of services, +in its own namespace \- to hold up the parts of an application, say, and +redeploy them by discarding the namespace and starting again. +.PP +When it is the program that brings a machine up, it does four more things. +.PP +It builds the base namespace that everything else inherits. Services run in +their own namespace groups and so cannot do this for one another. +.PP +It offers a shell on the console when the machine cannot be reached any other +way. +.PP +It stops the adopted root file server last, after everything that might be using +it. +.PP +It powers the machine off, or reboots it, which is what +.B halt +and +.B reboot +finally do. +.SH LOGGING +Everything a service writes to standard output or standard error is appended to +.BI /log/ name\fR. +.B /mnt/svcs/\fIname\fB/log +is a view of that file; reading it at the end blocks until there is more, so it +can be followed. +.PP +Nothing rotates these files. That is deliberate: appending is a few lines and +rotating is a program, and it is not going in init. +.PP +Before there is a writable filesystem, and again once shutdown has started, +there is nowhere to append to and messages go to the console instead. +.SH TESTING +Supervising services does not require being the program that boots the machine, +so +.I init +can be run as an ordinary program against a directory of test services: +.PP +.EX +init -d /tmp/svc.test -l /tmp/log.test -s svc.test -m /mnt/svcs.test +.EE +.PP +Give +.B -l +as well as the rest, or the test instance appends to the real +.BR /log . +.PP +What such an instance cannot exercise is the base namespace, the rescue console, +halting the adopted root file server, and any service with a +.B user +attribute, since changing identity needs the host owner. +.SH FILES +.TF /mnt/svcs +.TP +.B /lib/svc +service definitions +.TP +.B /mnt/svcs +the service filesystem +.TP +.B /srv/svc +where it is posted +.TP +.B /log +service output +.SH SOURCE +.B /sys/src/cmd/init.c +.br +.B /sys/src/cmd/svc +.SH SEE ALSO +.IR ndb , +.IR namespace , +.IR cap , +.IR srv , +.IR rc +.SH BUGS +A service written in +.I rc +must +.I exec +its final program rather than starting it with +.BR & . +Otherwise +.I init +supervises the shell, the shell exits immediately, and the program it started is +left running with nothing watching it. +.PP +There is no notification when a file changes, so a service watched by its +.B /srv +file is not noticed to have died until something looks. The entry itself is +removed when the server dies, with or without an active mount held on it, so +looking is enough; only the delay is at issue. +.PP +Nothing detects a service that is running but not answering. A wedged server +keeps both its process and its +.B /srv +entry and so reads as +.B running +under every +.B ready +form. Only a real 9P transaction would show otherwise, and +.I init +does not make one. +.PP +.B Reexec +keeps services running but not mounts: +anyone who already has +.B /srv/svc +mounted holds fids that cannot survive the exec, and has to mount it again. +.PP +On a machine that cannot be powered off, +.B halt +stops everything, says so, and leaves the machine running. +.PP +Nothing restarts +.I init +if it dies. +.PP +There is no resource control of any kind. |