X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemctl.xml;h=29481e718231e808c10687766285f5fe86b3709d;hp=1c5c884f8ce9b1efcb99216cda8847f361b6cf6d;hb=957eb8cab28dc83aa4b800d033031e53cd0a9e00;hpb=75676b7287c50b5e03ed0143c65b93d435ff8b6c diff --git a/man/systemctl.xml b/man/systemctl.xml index 1c5c884f8..29481e718 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,16 +121,26 @@ 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 + . + + Do not ellipsize unit - names in the output of + names and truncate unit descriptions + in the output of list-units and list-jobs. @@ -136,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. @@ -146,7 +180,7 @@ Suppress output to STDOUT in snapshot, - check, + is-active, enable and disable. @@ -154,13 +188,29 @@ - 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 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. + @@ -170,10 +220,10 @@ - + Talk to the systemd - session manager of the calling user. + manager of the calling user. @@ -216,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. @@ -233,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 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: @@ -318,37 +520,73 @@ 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] 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. 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 @@ -361,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...] @@ -395,23 +634,31 @@ - reset-maintenance [NAME...] - - Reset maintenance - 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 - maintenance state and its exit codes - and status is recorded for - introspection by the administrator + 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...] @@ -430,7 +677,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. @@ -447,7 +694,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 @@ -476,11 +723,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. @@ -496,14 +743,11 @@ 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 @@ -519,9 +763,9 @@ . - This command honours + This command honors , - , + , in a similar way as enable. @@ -535,8 +779,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. + @@ -578,17 +899,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 @@ -634,7 +945,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 @@ -689,16 +1000,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 @@ -731,7 +1032,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 @@ -739,7 +1067,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 @@ -748,46 +1088,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. @@ -800,11 +1197,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