X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemctl.xml;h=5edbb9fc3c0c6a48c2eb158cb7e3fb0c8d78c444;hp=88bc48fca520a81871c49051431c4f671c1a34f2;hb=b43f208f78666fd27e274daa946ae57becd59dd6;hpb=a9c72fe933efc9c77580fb4d7212e00f7a690c36 diff --git a/man/systemctl.xml b/man/systemctl.xml index 88bc48fca..5edbb9fc3 100644 --- a/man/systemctl.xml +++ b/man/systemctl.xml @@ -8,16 +8,16 @@ Copyright 2010 Lennart Poettering systemd is free software; you can redistribute it and/or modify it - under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or + under the terms of the GNU Lesser General Public License as published by + the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. systemd is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - General Public License for more details. + Lesser General Public License for more details. - You should have received a copy of the GNU General Public License + You should have received a copy of the GNU Lesser General Public License along with systemd; If not, see . --> @@ -44,7 +44,7 @@ systemctl - Control the systemd system and session manager + Control the systemd system and service manager @@ -59,7 +59,7 @@ systemctl may be used to introspect and control the state of the systemd1 - system and session manager. + system and service manager. @@ -76,6 +76,13 @@ text and exits. + + + + Prints a short version + string and exits. + + @@ -95,7 +102,7 @@ When showing - unit/job/manager information, limit + unit/job/manager properties, limit display to certain properties as specified as argument. If not specified all set properties are @@ -114,11 +121,20 @@ When listing units, show all units, regardless of their state, including inactive units. When - showing unit/job/manager information, + showing unit/job/manager properties, show all properties regardless whether they are set or not. + + + + When listing units, + show only failed units. Do not confuse + with + . + + @@ -137,7 +153,24 @@ unfinished job, fail the command. If this is not specified the requested operation will replace the pending job, - if necessary. + if necessary. Do not confuse + with + . + + + + + + When enqueuing a new + job ignore all its dependencies and + execute it immediately. If passed no + required units of the unit passed will + be pulled in, and no ordering + dependencies will be honoured. This is + mostly a debugging and rescue tool for + the administrator and should not be + used by + applications. @@ -147,7 +180,7 @@ Suppress output to STDOUT in snapshot, - check, + is-active, enable and disable. @@ -161,7 +194,23 @@ enqueued and systemctl will wait until it is completed. By passing this argument it is only verified and - enqueued. + enqueued. + + + + + + Do not print a legend, i.e. + the column headers and the footer with hints. + + + + + + + Do not pipe output into a + pager. + @@ -171,10 +220,10 @@ - + Talk to the systemd - session manager of the calling user. + manager of the calling user. @@ -217,10 +266,10 @@ When used with enable and disable, operate on the - global session configuŕation + global user configuration directory, thus enabling or disabling a unit file globally for all future - sessions of all users. + logins of all users. @@ -234,26 +283,178 @@ changes. + + + + When used with + start and related + commands, disables asking for + passwords. Background services may + require input of a password or + passphrase string, for example to + unlock system hard disks or + cryptographic certificates. Unless + this option is specified and the + command is invoked from a terminal + systemctl will + query the user on the terminal for the + necessary secrets. Use this option to + switch this behavior off. In this case + the password must be supplied by some + other means (for example graphical + password agents) or the service might + fail. This also disables querying the + user for authentication for privileged + operations. + + + + + + When used with + kill, choose which + processes to kill. Must be one of + , + or + to select whether + to kill only the main process of the + unit, the control process or all + processes of the unit. If omitted + defaults to + . + + + + + + + When used with + kill, choose which + signal to send to selected + processes. Must be one of the well + known signal specifiers such as + SIGTERM, SIGINT or SIGSTOP. If + omitted defaults to + . + + + When used with - enable, override any + enable, overwrite any existing conflicting symlinks. + + When used with + halt, + poweroff, + reboot or + kexec execute the + selected operation without shutting + down all units. However, all processes + will be killed forcibly and all file + systems are unmounted or remounted + read-only. This is hence a drastic but + relatively safe option to request an + immediate reboot. If + is specified + twice for these operations, they will + be executed immediately without + terminating any processes or umounting + any file systems. Warning: specifying + twice with + any of these operations might result + in data loss. + + + + + + When used with + enable/disable/is-enabled (and + related commands), use alternative + root path when looking for unit + files. - + When used with - disable, ensures - that only the symlinks created by - enable are removed, - not all symlinks pointing to the unit - file that shall be - disabled. + enable/disable/is-enabled (and related commands), make + changes only temporarily, so that they + are dropped on the next reboot. This + will have the effect that changes are + not made in subdirectories of + /etc but in + /run, with + identical immediate effects, however, + since the latter is lost on reboot, + the changes are lost + too. + + + + + + Execute operation + remotely. Specify a hostname, or + username and hostname separated by @, + to connect to. This will use SSH to + talk to the remote systemd + instance. + + + + + + + Acquire privileges via + PolicyKit before executing the + operation. + + + + + + + When used with + status controls the + number of journal lines to show, + counting from the most recent + ones. Takes a positive integer + argument. Defaults to + 10. + + + + + + + When used with + status continously + prints new journal entries as they are + appended to the + journal. + + + + + + + When used with + status controls the + formatting of the journal entries that + are shown. For the available choices + see + journalctl1. Defaults + to + short. + + The following commands are understood: @@ -319,23 +520,34 @@ Restart one or more units specified on the command - line. If the units are not running yet - the operation will - fail. + line if the units are running. Do + nothing if units are not running. + Note that for compatibility + with Red Hat init scripts + condrestart is + equivalent to this command. reload-or-restart [NAME...] + + Reload one or more + units if they support it. If not, + restart them instead. If the units + are not running yet they will be + started. + + reload-or-try-restart [NAME...] Reload one or more units if they support it. If not, - restart them instead. Note that for - compatibility with SysV and Red Hat - init scripts - force-reload and - condrestart may be - used as equivalent commands to - reload-or-try-restart. + restart them instead. Do nothing if + the units are not running. Note that + for compatibility with SysV init + scripts + force-reload is + equivalent to this + command. isolate [NAME] @@ -358,11 +570,23 @@ systemd.unit5 for details. + + kill [NAME...] + + Send a signal to one + or more processes of the unit. Use + to select + which process to kill. Use + to + select the kill mode and + to select + the signal to send. + is-active [NAME...] Check whether any of - the specified units is active + the specified units are active (i.e. running). Returns an exit code 0 if at least one is active, non-zero otherwise. Unless @@ -375,14 +599,15 @@ Show terse runtime status information about one or more - units. This function is intended to - generate human-readable output. If you - are looking for computer-parsable - output, use show - instead. If a PID is passed - information about the unit the process - of the PID belongs to is - shown. + units, followed by its most recent log + data from the journal. This function + is intended to generate human-readable + output. If you are looking for + computer-parsable output, use + show instead. If a + PID is passed information about the + unit the process of the PID belongs to + is shown. show [NAME...|JOB...] @@ -407,7 +632,15 @@ looking for formatted human-readable output. + + help [NAME...|PID...] + Show manual pages for + one or more units, if available. If a + PID is passed the manual pages for the + unit the process of the PID belongs to + is shown. + reset-failed [NAME...] @@ -427,6 +660,13 @@ command. + + list-unit-files + + List installed unit files. + + + enable [NAME...] @@ -445,7 +685,7 @@ does not have the effect that any of the units enabled are also started at the same time. If this is desired a - seperate start + separate start command must be invoked for the unit. @@ -462,7 +702,7 @@ administrator is free to make additional changes manually, by placing or removing symlinks in the - directory. This is particular useful + directory. This is particularly useful to create configurations that deviate from the suggested default installation. In this case the @@ -491,11 +731,11 @@ Depending on whether , - or + or is specified this enables the unit for the system, - for sessions of the calling user only - or for all future session of all + for the calling user only + or for all future logins of all users. Note that in the latter case no systemd daemon configuration is reloaded. @@ -511,21 +751,18 @@ configuration directory, and hence undoes the changes made by enable. Note - however that this by default removes + however that this removes all symlinks to the unit files (i.e. including manual additions), not just those actually created by - enable. If only the - symlinks that are suggested by default - shall be removed, pass - . This + enable. This call implicitly reloads the systemd daemon configuration after completing the disabling of the units. Note that this command does not implicitly stop the units that is being disabled. If this is desired an additional - stopcommand should + stop command should be executed afterwards. This command will print the @@ -534,9 +771,9 @@ . - This command honours + This command honors , - , + , in a similar way as enable. @@ -550,8 +787,85 @@ (as with enable). Returns an exit code of 0 if at least one is - enabled, non-zero - otherwise. + enabled, non-zero otherwise. Prints + the current enable status. To suppress + this output use + . + + + + reenable [NAME...] + + Reenable one or more + unit files, as specified on the + command line. This is a combination of + disable and + enable and is + useful to reset the symlinks a unit is + enabled with to the defaults + configured in the + [Install] section + of the unit file. + + + + + preset [NAME...] + + Reset one or more unit + files, as specified on the command + line, to the defaults configured in a + preset file. This has the same effect + as disable or + enable, depending + how the unit is listed in the preset + files. + + + + + mask [NAME...] + + Mask one or more unit + files, as specified on the command + line. This will link these units to + /dev/null, making + it impossible to start them. This is a stronger version + of disable, since + it prohibits all kinds of activation + of the unit, including manual + activation. Use this option with + care. + + + + + unmask [NAME...] + + Unmask one or more + unit files, as specified on the + command line. This will undo the + effect of + mask. + + + + + link [NAME...] + + Link a unit file that + is not in the unit file search paths + into the unit file search path. This + requires an absolute path to a unit + file. The effect of this can be undone + with disable. The + effect of this command is that a unit + file is available for + start and other + commands although it isn't installed + directly in the unit search + path. + @@ -593,17 +907,7 @@ Cancel one or more jobs specified on the command line by their numeric job - IDs. If not job id is specified cancels all jobs that are pending. - - - monitor - - Monitor unit/job - changes. This is mostly useful for - debugging purposes and prints a line - each time systemd loads or unloads a - unit configuration file, or a unit - property changes. + IDs. If no job id is specified, cancel all pending jobs. dump @@ -649,7 +953,7 @@ A snapshot refers to a saved state of the systemd manager. It is - implemented itself as unit that is + implemented itself as a unit that is generated dynamically with this command and has dependencies on all units active at the time. At a later @@ -704,16 +1008,6 @@ configuration will stay accessible. - - daemon-exit - - Ask the systemd - manager to quit. This is only - supported for session managers - (i.e. in conjunction with the - option) and - will fail otherwise. - show-environment @@ -746,7 +1040,34 @@ is only removed if it has the specified value. + + default + Enter default + mode. This is mostly equivalent to + start + default.target. + + + rescue + + Enter rescue + mode. This is mostly equivalent to + isolate + rescue.target but also + prints a wall message to all + users. + + + emergency + + Enter emergency + mode. This is mostly equivalent to + isolate + emergency.target but also + prints a wall message to all + users. + halt @@ -754,7 +1075,19 @@ system. This is mostly equivalent to start halt.target but also prints a wall message to all - users. + users. If combined with + shutdown of + all running services is skipped, + however all processes are killed and + all file systems are unmounted or + mounted read-only, immediately + followed by the system halt. If + is specified + twice the the operation is immediately + executed without terminating any + processes or unmounting any file + systems. This may result in data + loss. poweroff @@ -763,46 +1096,103 @@ power-off the system. This is mostly equivalent to start poweroff.target but also - prints a wall message to all - users. + prints a wall message to all users. If + combined with + shutdown of all running services is + skipped, however all processes are + killed and all file systems are + unmounted or mounted read-only, + immediately followed by the powering + off. If is + specified twice the the operation is + immediately executed without + terminating any processes or + unmounting any file systems. This may + result in data loss. reboot - Shut down and - reboot the system. This is mostly - equivalent to start + Shut down and reboot + the system. This is mostly equivalent + to start reboot.target but also - prints a wall message to all - users. + prints a wall message to all users. If + combined with + shutdown of all running services is + skipped, however all processes are + killed and all file systems are + unmounted or mounted read-only, + immediately followed by the reboot. If + is specified + twice the the operation is immediately + executed without terminating any + processes or unmounting any file + systems. This may result in data + loss. - default + kexec - Enter default - mode. This is mostly equivalent to - start - default.target. + Shut down and reboot + the system via kexec. This is mostly + equivalent to start + kexec.target but also prints + a wall message to all users. If + combined with + shutdown of all running services is + skipped, however all processes are killed + and all file systems are unmounted or + mounted read-only, immediately + followed by the + reboot. - rescue + exit - Enter rescue - mode. This is mostly equivalent to - isolate - rescue.target but also - prints a wall message to all - users. + Ask the systemd + manager to quit. This is only + supported for user service managers + (i.e. in conjunction with the + option) and + will fail otherwise. - emergency + suspend - Enter emergency - mode. This is mostly equivalent to - isolate - emergency.target but also - prints a wall message to all - users. + Suspend the system. + + + hibernate + + Hibernate the system. + + + switch-root [ROOT] [INIT] + + Switches to a + different root directory and executes + a new system manager process below + it. This is intended for usage in + initial RAM disks ("initrd"), and will + transition from the initrd's system + manager process (a.k.a "init" process) + to the main system manager + process. Takes two arguments: the + directory to make the new root + directory, and the path to the new + system manager binary below it to + execute as PID 1. If the latter is + ommitted or the empty string, a + systemd binary will automatically be + searched for and used as init. If the + system manager path is ommitted or + equal the empty string the state of + the initrd's system manager process is + passed to the main system manager, + which allows later introspection of the + state of the services involved in the + initrd boot. @@ -815,11 +1205,29 @@ code otherwise. + + Environment + + + + $SYSTEMD_PAGER + Pager to use when + is not given; + overrides $PAGER. Setting + this to an empty string or the value + cat is equivalent to passing + . + + + + See Also systemd1, systemadm1, + journalctl1, + loginctl1, systemd.unit5, systemd.special7, wall1