X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemctl.xml;h=f22338371635d170530ba703c43f0805903401ff;hp=c0b8d7927d10dc6d7e0574ccf0601b9ab1cd2369;hb=55c0b89c575fcb2c075286d444ed4fb1cf8c8563;hpb=61cbdc4b307718d74e8aa04875475aac2f8617ab diff --git a/man/systemctl.xml b/man/systemctl.xml index c0b8d7927..f22338371 100644 --- a/man/systemctl.xml +++ b/man/systemctl.xml @@ -8,20 +8,20 @@ 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 . --> - + systemctl @@ -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,18 +76,42 @@ text and exits. + + + + Prints a short version + string and exits. + + - When listing units, - limit display to certain unit - types. If not specified units of all - types will be shown. The argument - should be a unit type name such as - , - and - similar. + The argument should + be a unit type name such as + and + , + or a unit load state such as + and + . + + + If the argument is a unit type, + when listing units, limit display to + certain unit types. If not specified + units of all types will be shown. + + If the argument is a unit load state, + when listing units, limit display to + certain unit types. If not specified + units of in all load states will be + shown. + + As a special case, if the argument + is , a list of + allowed values will be printed and the + program will exit. + @@ -95,12 +119,16 @@ When showing - unit/job/manager information, limit - display to certain property names. If - not specified all set properties are + unit/job/manager properties, limit + display to certain properties as + specified as argument. If not + specified all set properties are shown. The argument should be a property name, such as - MainPID. + MainPID. If + specified more than once all + properties with the specified names + are shown. @@ -110,56 +138,163 @@ 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. - + - If the requested - operation conflicts with an existing - unfinished operation, replace the - existing operation by the requested - operation. If this is not specified - the requested operation will - fail. + When listing units, + show only failed units. Do not confuse + with + . - + - Talk to the systemd - system manager. (Default) + Do not ellipsize unit + names, cgroup members, and truncate unit descriptions + in the output of + list-units and + list-jobs. - + - Talk to the systemd - session manager of the calling user. + If the requested + operation conflicts with a pending + unfinished job, fail the command. If + this is not specified the requested + operation will replace the pending job, + 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 honored. This is + mostly a debugging and rescue tool for + the administrator and should not be + used by + applications. + - Do not synchronously wait for - the requested operation to finish. If this is - not specified the job will be verified, - enqueued and systemctl will - wait until it is completed. By passing this - argument it is only verified and - enqueued. + + + + + When system shutdown + or a sleep state is requested, ignore + inhibitor locks. Applications can + establish inhibitor locks to avoid + that certain important operations + (such as CD burning or suchlike) are + interrupted by system shutdown or a + sleep state. Any user may take these + locks and privileged users may + override these locks. If any locks are + taken, shutdown and sleep state + requests will normally fail + (regardless if privileged or not) and + list of active locks is + printed. However if + + is specified the locks are ignored and + not printed, and the operation + attempted anyway, possibly requiring + additional + privileges. + Suppress output to - STDOUT for snapshot - and - check. + STDOUT in + snapshot, + is-active, + is-failed, + enable and + disable. + + + + + + Do not synchronously wait for + the requested operation to finish. If this is + not specified the job will be verified, + enqueued and systemctl will + wait until it is completed. By passing this + argument it is only verified and + enqueued. + + + + + + Do not print a legend, i.e. + the column headers and the footer with hints. + + + + + + + Do not pipe output into a + pager. + + + + + + Talk to the systemd + system manager. (Default) + + + + + + Talk to the systemd + manager of the calling user. + + + + + + + When used in + conjunction with the + dot command (see + below), selects which dependencies are + shown in the dependency graph. If + is passed + only dependencies of type + After= or + Before= are + shown. If + is passed only dependencies of type + Requires=, + RequiresOverridable=, + Requisite=, + RequisiteOverridable=, + Wants= and + Conflicts= are + shown. If neither is passed, shows + dependencies of all these + types. @@ -169,6 +304,191 @@ message before halt, power-off, reboot. + + + + + When used with + enable and + disable, operate on the + global user configuration + directory, thus enabling or disabling + a unit file globally for all future + logins of all users. + + + + + + When used with + enable and + disable, do not + implicitly reload daemon configuration + after executing the + 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, 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 + 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 controls the + formatting of the journal entries that + are shown. For the available choices + see + journalctl1. Defaults + to + short. + + The following commands are understood: @@ -182,36 +502,28 @@ start [NAME...] - Start one or more - units specified on the command + Start (activate) one + or more units specified on the command line. stop [NAME...] - Stop one or more units - specified on the command - line. - - - restart [NAME...] - - Restart one or more - units specified on the command + Stop (deactivate) one + or more units specified on the command line. reload [NAME...] - Asks all services - whose units are listed on the command - line to reload their + Asks all units listed + on the command line to reload their configuration. Note that this will - reload the daemon configuration - itself, not the unit configuration - file of systemd. If you want systemd - to reload the configuration file of a - unit use the + reload the service-specific + configuration, not the unit + configuration file of systemd. If you + want systemd to reload the + configuration file of a unit use the daemon-reload command. In other words: for the example case of Apache, this will @@ -219,55 +531,401 @@ httpd.conf in the web server, not the apache.service - systemd unit file. This - command should not be confused with - the daemon-reload - or load + systemd unit file. + + This command should not be + confused with the + daemon-reload or + load commands. + + restart [NAME...] + + Restart one or more + units specified on the command + line. If the units are not running yet + they will be + started. + + + try-restart [NAME...] + + Restart one or more + units specified on the command + 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. 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] Start the unit specified on the command line and its - dependencies and stop all - others. + dependencies and stop all others. + + This is similar to changing the + runlevel in a traditional init system. The + isolate command will + immediately stop processes that are not + enabled in the new unit, possibly including + the graphical environment or terminal you + are currently using. + + Note that this works only on units + where is + enabled. See + 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. - check [NAME...] + is-active [NAME...] Check whether any of - the specified units is active - (i.e. running). Returns 0 if at least - one is active, non-zero + the specified units are active + (i.e. running). Returns an exit code + 0 if at least one is active, non-zero otherwise. Unless is specified this will also print the current unit state to STDOUT. - status [NAME...] + is-failed [NAME...] - Show short status - information about one or more - units. This shows terse runtime - information about - units. + Check whether any of + the specified units are failed. + Returns an exit code + 0 if at least one is failed, non-zero + otherwise. Unless + is specified + this will also print the current unit + state to STDOUT. + + + status [NAME...|PID...] + + Show terse runtime + status information about one or more + 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...] - Show properties of - one or more units, jobs or the manager + Show properties of one + or more units, jobs or the manager itself. If no argument is specified properties of the manager will be shown. If a unit name is specified - properties of the unit is shown, - and if a job id is specified - properties of the job is - shown. + properties of the unit is shown, and + if a job id is specified properties of + the job is shown. By default, empty + properties are suppressed. Use + to show those + too. To select specific properties to + show use + . This + command is intended to be used + whenever computer-parsable output is + required. Use + status if you are + 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...] + + Reset the + 'failed' state of the + specified units, or if no unit name is + passed of all units. When a unit fails + in some way (i.e. process exiting with + non-zero error code, terminating + abnormally or timing out) it will + automatically enter the + 'failed' state and + its exit code and status is recorded + for introspection by the administrator + until the service is restarted or + reset with this + command. + + + + list-unit-files + + List installed unit files. + + + + + enable [NAME...] + + Enable one or + more unit files or unit file + instances, as specified on the + command line. This will create a + number of symlinks as encoded in + the [Install] + sections of the unit files. After + the symlinks have been created the + systemd configuration is reloaded + (in a way that is equivalent to + daemon-reload) + to ensure the changes are taken into + account immediately. Note that this + does not have the effect that any of + the units enabled are also started at + the same time. If this is desired + a separate start + command must be invoked for the unit. + Also note that in case of instance + enablement, symlinks named same as + instances are created in install + location, however they all point to + the same template unit file. + + This command will + print the actions executed. This + output may be suppressed by passing + . + + Note that this operation creates + only the suggested symlinks for the + units. While this command is the + recommended way to manipulate the unit + configuration directory, the + administrator is free to make + additional changes manually, by + placing or removing symlinks in the + directory. This is particularly useful + to create configurations that deviate + from the suggested default + installation. In this case the + administrator must make sure to invoke + daemon-reload + manually as necessary, to ensure his + changes are taken into account. + + Enabling units should not be + confused with starting (activating) + units, as done by the + start + command. Enabling and starting units + is orthogonal: units may be enabled + without being started and started + without being enabled. Enabling simply + hooks the unit into various suggested + places (for example, so that the unit + is automatically started on boot or + when a particular kind of hardware is + plugged in). Starting actually spawns + the daemon process (in case of service + units), or binds the socket (in case + of socket units), and so + on. + + Depending on whether + , + or + is specified + this enables the unit for the system, + 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. + + + + + disable [NAME...] + + Disables one or more + units. This removes all symlinks to + the specified unit files from the unit + configuration directory, and hence + undoes the changes made by + enable. Note + however that this removes + all symlinks to the unit files + (i.e. including manual additions), not + just those actually created by + 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 are being disabled. If this + is desired an additional + stop command should + be executed afterwards. + + This command will print the + actions executed. This output may be + suppressed by passing + . + + + This command honors + , + , + in a similar + way as + enable. + + + + is-enabled [NAME...] + + Checks whether any of + the specified unit files are enabled + (as with + enable). Returns an + exit code of 0 if at least one is + 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 + the preset policy files. This has the + same effect as + disable or + enable, depending + how the unit is listed in the preset + files. For more information on preset + policy format see + systemd.preset5. For + more information on the concept of + presets please consult the Preset + document. + + + + + 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. + + load [NAME...] @@ -307,22 +965,7 @@ Cancel one or more jobs specified on the command line by their numeric job - IDs. - - - clear-jobs - - Cancel all jobs that are in progress. - - - 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 @@ -335,6 +978,35 @@ be parsed by applications. + + dot + + Generate textual + dependency graph description in dot + format for further processing with the + GraphViz + dot1 + tool. Use a command line like + systemctl dot | dot -Tsvg > + systemd.svg to generate a + graphical dependency tree. Unless + or + is passed + the generated graph will show both + ordering and requirement + dependencies. + + + list-dependencies [NAME] + + + Shows required and wanted units of given unit. + Target units are recursively expanded. + When is passed + dependency tree is generated for all + subsidiary units. + + snapshot [NAME] @@ -350,7 +1022,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 @@ -381,7 +1053,7 @@ unit files and recreate the entire dependency tree. While the daemon is reloaded, all sockets systemd listens - on on behalf of user configuration, will + on on behalf of user configuration will stay accessible. This command should not be confused with the load or @@ -405,16 +1077,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 @@ -447,7 +1109,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 @@ -455,7 +1144,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 operation is immediately + executed without terminating any + processes or unmounting any file + systems. This may result in data + loss. poweroff @@ -464,46 +1165,120 @@ 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 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 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.service but also - prints a wall message to all - users. + Suspend the + system. This will trigger activation + of the special + suspend.target + target. + + + hibernate + + Hibernate the + system. This will trigger activation + of the special + hibernate.target + target. + + + hybrid-sleep + + Hibernate and suspend + the system. This will trigger + activation of the special + hybrid-sleep.target + target. + + + 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 + omitted or the empty string, a + systemd binary will automatically be + searched for and used as init. If the + system manager path is omitted 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. @@ -516,14 +1291,33 @@ 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 + wall1, + systemd.preset5