diff options
Diffstat (limited to 'src/grp-system/systemctl/systemctl.xml')
| -rw-r--r-- | src/grp-system/systemctl/systemctl.xml | 294 |
1 files changed, 141 insertions, 153 deletions
diff --git a/src/grp-system/systemctl/systemctl.xml b/src/grp-system/systemctl/systemctl.xml index 991e9bafaf..e7880d24f7 100644 --- a/src/grp-system/systemctl/systemctl.xml +++ b/src/grp-system/systemctl/systemctl.xml @@ -150,11 +150,11 @@ <term><option>--all</option></term> <listitem> - <para>When listing units, show all loaded units, regardless - of their state, including inactive units. When showing - unit/job/manager properties, show all properties regardless - whether they are set or not.</para> - <para>To list all units installed on the system, use the + <para>When listing units with <command>list-units</command>, also show inactive units and + units which are following other units. When showing unit/job/manager properties, show all + properties regardless whether they are set or not.</para> + + <para>To list all units installed in the file system, use the <command>list-unit-files</command> command instead.</para> </listitem> </varlistentry> @@ -481,19 +481,19 @@ <para>When used with <command>enable</command>, overwrite any existing conflicting symlinks.</para> - <para>When used with <command>halt</command>, - <command>poweroff</command>, <command>reboot</command> or - <command>kexec</command>, 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 - <option>--force</option> is specified twice for these - operations, they will be executed immediately without - terminating any processes or unmounting any file - systems. Warning: specifying <option>--force</option> twice - with any of these operations might result in data - loss.</para> + <para>When used with <command>edit</command>, create all of the + specified units which do not already exist.</para> + + <para>When used with <command>halt</command>, <command>poweroff</command>, <command>reboot</command> or + <command>kexec</command>, 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 <option>--force</option> is specified + twice for these operations (with the exception of <command>kexec</command>), they will be executed + immediately, without terminating any processes or unmounting any file systems. Warning: specifying + <option>--force</option> twice with any of these operations might result in data loss. Note that when + <option>--force</option> is specified twice the selected operation is executed by + <command>systemctl</command> itself, and the system manager is not contacted. This means the command should + succeed even when the system manager hangs or crashed.</para> </listitem> </varlistentry> @@ -638,10 +638,13 @@ <term><command>list-units <optional><replaceable>PATTERN</replaceable>...</optional></command></term> <listitem> - <para>List known units (subject to limitations specified - with <option>-t</option>). If one or more - <replaceable>PATTERN</replaceable>s are specified, only - units matching one of them are shown.</para> + <para>List units that <command>systemd</command> has loaded. This includes units that + are either referenced directly or through a dependency, or units that were active in the + past and have failed. By default only units which are active, have pending jobs, or have + failed are shown; this can be changed with option <option>--all</option>. If one or more + <replaceable>PATTERN</replaceable>s are specified, only units matching one of them are + shown. The units that are shown are additionally filtered by <option>--type=</option> + and <option>--state=</option> if those options are specified.</para> <para>This is the default command.</para> </listitem> @@ -970,71 +973,61 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <term><command>list-unit-files <optional><replaceable>PATTERN...</replaceable></optional></command></term> <listitem> - <para>List installed unit files and their enablement state - (as reported by <command>is-enabled</command>). If one or - more <replaceable>PATTERN</replaceable>s are specified, - only units whose filename (just the last component of the - path) matches one of them are shown.</para> + <para>List unit files installed on the system, in combination with their enablement state (as reported by + <command>is-enabled</command>). If one or more <replaceable>PATTERN</replaceable>s are specified, only unit + files whose name matches one of them are shown (patterns matching unit file system paths are not + supported).</para> </listitem> </varlistentry> <varlistentry> <term><command>enable <replaceable>NAME</replaceable>...</command></term> + <term><command>enable <replaceable>PATH</replaceable>...</command></term> <listitem> - <para>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 <literal>[Install]</literal> - sections of the unit files. After the symlinks have been - created, the systemd configuration is reloaded (in a way that - is equivalent to <command>daemon-reload</command>) to ensure - the changes are taken into account immediately. Note that - this does <emphasis>not</emphasis> have the effect of also - starting any of the units being enabled. If this - is desired, either <option>--now</option> should be used - together with this command, or an additional <command>start</command> - command must be invoked for the unit. Also note that, in case of - instance enablement, symlinks named the same as instances - are created in the install location, however they all point to the - same template unit file.</para> - - <para>This command will print the actions executed. This - output may be suppressed by passing <option>--quiet</option>. + <para>Enable one or more units or unit instances. This will create a set of symlinks, as encoded in the + <literal>[Install]</literal> sections of the indicated unit files. After the symlinks have been created, + the system manager configuration is reloaded (in a way equivalent to <command>daemon-reload</command>), in + order to ensure the changes are taken into account immediately. Note that this does + <emphasis>not</emphasis> have the effect of also starting any of the units being enabled. If this is + desired, combine this command with the <option>--now</option> switch, or invoke <command>start</command> + with appropriate arguments later. Note that in case of unit instance enablement (i.e. enablement of units of + the form <filename>foo@bar.service</filename>), symlinks named the same as instances are created in the + unit configuration diectory, however they point to the single template unit file they are instantiated + from.</para> + + <para>This command expects either valid unit names (in which case various unit file directories are + automatically searched for unit files with appropriate names), or absolute paths to unit files (in which + case these files are read directly). If a specified unit file is located outside of the usual unit file + directories, an additional symlink is created, linking it into the unit configuration path, thus ensuring + it is found when requested by commands such as <command>start</command>.</para> + + <para>This command will print the file system operations executed. This output may be suppressed by passing + <option>--quiet</option>. </para> - <para>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 <command>daemon-reload</command> manually as - necessary to ensure the changes are taken into account. + <para>Note that this operation creates only the symlinks suggested in the <literal>[Install]</literal> + section of the unit files. 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 + below this 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 + <command>daemon-reload</command> manually as necessary, in order to ensure the changes are taken into + account. </para> - <para>Enabling units should not be confused with starting - (activating) units, as done by the <command>start</command> - 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.</para> - - <para>Depending on whether <option>--system</option>, - <option>--user</option>, <option>--runtime</option>, - or <option>--global</option> is specified, this enables the unit - for the system, for the calling user only, for only this boot of - the system, or for all future logins of all users, or only this - boot. Note that in the last case, no systemd daemon - configuration is reloaded.</para> - - <para>Using <command>enable</command> on masked units - results in an error.</para> + <para>Enabling units should not be confused with starting (activating) units, as done by the + <command>start</command> 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.</para> + + <para>Depending on whether <option>--system</option>, <option>--user</option>, <option>--runtime</option>, + or <option>--global</option> is specified, this enables the unit for the system, for the calling user only, + for only this boot of the system, or for all future logins of all users, or only this boot. Note that in + the last case, no systemd daemon configuration is reloaded.</para> + + <para>Using <command>enable</command> on masked units is not supported and results in an error.</para> </listitem> </varlistentry> @@ -1042,28 +1035,31 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <term><command>disable <replaceable>NAME</replaceable>...</command></term> <listitem> - <para>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 - <command>enable</command>. Note however that this removes - all symlinks to the unit files (i.e. including manual - additions), not just those actually created by - <command>enable</command>. 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, either - <option>--now</option> should be used together with this command, or - an additional <command>stop</command> command should be executed - afterwards.</para> - - <para>This command will print the actions executed. This - output may be suppressed by passing <option>--quiet</option>. + <para>Disables one or more units. This removes all symlinks to the unit files backing the specified units + from the unit configuration directory, and hence undoes any changes made by <command>enable</command> or + <command>link</command>. Note that this removes <emphasis>all</emphasis> symlinks to matching unit files, + including manually created symlinks, and not just those actually created by <command>enable</command> or + <command>link</command>. Note that while <command>disable</command> undoes the effect of + <command>enable</command>, the two commands are otherwise not symmetric, as <command>disable</command> may + remove more symlinks than a prior <command>enable</command> invocation of the same unit created.</para> + + <para>This command expects valid unit names only, it does not accept paths to unit files.</para> + + <para>In addition to the units specified as arguments, all units are disabled that are listed in the + <varname>Also=</varname> setting contained in the <literal>[Install]</literal> section of any of the unit + files being operated on.</para> + + <para>This command implicitly reloads the system manager configuration after completing the operation. Note + that this command does not implicitly stop the units that are being disabled. If this is desired, either + combine this command with the <option>--now</option> switch, or invoke the <command>stop</command> command + with appropriate arguments later.</para> + + <para>This command will print information about the file system operations (symlink removals) + executed. This output may be suppressed by passing <option>--quiet</option>. </para> - <para>This command honors <option>--system</option>, - <option>--user</option>, <option>--runtime</option> and - <option>--global</option> in a similar way as - <command>enable</command>.</para> + <para>This command honors <option>--system</option>, <option>--user</option>, <option>--runtime</option> + and <option>--global</option> in a similar way as <command>enable</command>.</para> </listitem> </varlistentry> @@ -1071,12 +1067,10 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <term><command>reenable <replaceable>NAME</replaceable>...</command></term> <listitem> - <para>Reenable one or more unit files, as specified on the - command line. This is a combination of - <command>disable</command> and <command>enable</command> and - is useful to reset the symlinks a unit is enabled with to - the defaults configured in the <literal>[Install]</literal> - section of the unit file.</para> + <para>Reenable one or more units, as specified on the command line. This is a combination of + <command>disable</command> and <command>enable</command> and is useful to reset the symlinks a unit file is + enabled with to the defaults configured in its <literal>[Install]</literal> section. This commands expects + a unit uname only, it does not accept paths to unit files.</para> </listitem> </varlistentry> @@ -1207,16 +1201,13 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <term><command>mask <replaceable>NAME</replaceable>...</command></term> <listitem> - <para>Mask one or more unit files, as specified on the - command line. This will link these units to - <filename>/dev/null</filename>, making it impossible to - start them. This is a stronger version of - <command>disable</command>, since it prohibits all kinds of - activation of the unit, including enablement and manual - activation. Use this option with care. This honors the - <option>--runtime</option> option to only mask temporarily - until the next reboot of the system. The <option>--now</option> - option can be used to ensure that the units are also stopped.</para> + <para>Mask one or more units, as specified on the command line. This will link these unit files to + <filename>/dev/null</filename>, making it impossible to start them. This is a stronger version of + <command>disable</command>, since it prohibits all kinds of activation of the unit, including enablement + and manual activation. Use this option with care. This honors the <option>--runtime</option> option to only + mask temporarily until the next reboot of the system. The <option>--now</option> option may be used to + ensure that the units are also stopped. This command expects valid unit names only, it does not accept unit + file paths.</para> </listitem> </varlistentry> @@ -1224,23 +1215,20 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <term><command>unmask <replaceable>NAME</replaceable>...</command></term> <listitem> - <para>Unmask one or more unit files, as specified on the - command line. This will undo the effect of - <command>mask</command>.</para> + <para>Unmask one or more unit files, as specified on the command line. This will undo the effect of + <command>mask</command>. This command expects valid unit names only, it does not accept unit file + paths.</para> </listitem> </varlistentry> <varlistentry> - <term><command>link <replaceable>FILENAME</replaceable>...</command></term> + <term><command>link <replaceable>PATH</replaceable>...</command></term> <listitem> - <para>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 <command>disable</command>. The effect of this - command is that a unit file is available for - <command>start</command> and other commands although it - is not installed directly in the unit search path.</para> + <para>Link a unit file that is not in the unit file search paths into the unit file search path. This + command expects an absolute path to a unit file. The effect of this may be undone with + <command>disable</command>. The effect of this command is that a unit file is made available for commands + such as <command>start</command>, even though it is not installed directly in the unit search path.</para> </listitem> </varlistentry> @@ -1304,6 +1292,9 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <para>If <option>--full</option> is specified, this will copy the original units instead of creating drop-in files.</para> + <para>If <option>--force</option> is specified and any units do + not already exist, new unit files will be opened for editing.</para> + <para>If <option>--runtime</option> is specified, the changes will be made temporarily in <filename>/run</filename> and they will be lost on the next reboot.</para> @@ -1600,48 +1591,45 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <term><command>halt</command></term> <listitem> - <para>Shut down and halt the system. This is mostly equivalent to - <command>start halt.target --job-mode=replace-irreversibly</command>, but also - prints a wall message to all users. If combined with - <option>--force</option>, 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 <option>--force</option> is - specified twice, the operation is immediately executed - without terminating any processes or unmounting any file - systems. This may result in data loss.</para> + <para>Shut down and halt the system. This is mostly equivalent to <command>start halt.target + --job-mode=replace-irreversibly</command>, but also prints a wall message to all users. If combined with + <option>--force</option>, 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 + <option>--force</option> is specified twice, the operation is immediately executed without terminating any + processes or unmounting any file systems. This may result in data loss. Note that when + <option>--force</option> is specified twice the halt operation is executed by + <command>systemctl</command> itself, and the system manager is not contacted. This means the command should + succeed even when the system manager hangs or crashed.</para> </listitem> </varlistentry> <varlistentry> <term><command>poweroff</command></term> <listitem> - <para>Shut down and power-off the system. This is mostly - equivalent to <command>start poweroff.target --job-mode=replace-irreversibly</command>, - but also prints a wall message to all users. If combined with - <option>--force</option>, 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 <option>--force</option> is - specified twice, the operation is immediately executed - without terminating any processes or unmounting any file - systems. This may result in data loss.</para> + <para>Shut down and power-off the system. This is mostly equivalent to <command>start poweroff.target + --job-mode=replace-irreversibly</command>, but also prints a wall message to all users. If combined with + <option>--force</option>, 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 + <option>--force</option> is specified twice, the operation is immediately executed without terminating any + processes or unmounting any file systems. This may result in data loss. Note that when + <option>--force</option> is specified twice the power-off operation is executed by + <command>systemctl</command> itself, and the system manager is not contacted. This means the command should + succeed even when the system manager hangs or crashed.</para> </listitem> </varlistentry> <varlistentry> <term><command>reboot <optional><replaceable>arg</replaceable></optional></command></term> <listitem> - <para>Shut down and reboot the system. This is mostly - equivalent to <command>start reboot.target --job-mode=replace-irreversibly</command>, - but also prints a wall message to all users. If combined with - <option>--force</option>, 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 <option>--force</option> is - specified twice, the operation is immediately executed - without terminating any processes or unmounting any file - systems. This may result in data loss.</para> + <para>Shut down and reboot the system. This is mostly equivalent to <command>start reboot.target + --job-mode=replace-irreversibly</command>, but also prints a wall message to all users. If combined with + <option>--force</option>, 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 + <option>--force</option> is specified twice, the operation is immediately executed without terminating any + processes or unmounting any file systems. This may result in data loss. Note that when + <option>--force</option> is specified twice the reboot operation is executed by + <command>systemctl</command> itself, and the system manager is not contacted. This means the command should + succeed even when the system manager hangs or crashed.</para> <para>If the optional argument <replaceable>arg</replaceable> is given, it will be passed |