From 3990961df02a255cb75cc80445535d153fc7f165 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Mon, 25 Jul 2016 15:10:15 +0200 Subject: man: update systemctl man page for unit file commands, in particular "systemctl enable" Clarify that "systemctl enable" can operate either on unit names or on unit file paths (also, adjust the --help text to clarify this). Say that "systemctl enable" on unit file paths also links the unit into the search path. Many other fixes. This should improve the documentation to avoid further confusion around #3706. --- man/systemctl.xml | 187 +++++++++++++++++++++------------------------- src/systemctl/systemctl.c | 2 +- 2 files changed, 88 insertions(+), 101 deletions(-) diff --git a/man/systemctl.xml b/man/systemctl.xml index 742da81cfe..c7b830b7fb 100644 --- a/man/systemctl.xml +++ b/man/systemctl.xml @@ -973,70 +973,62 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service list-unit-files PATTERN... - List unit files installed in the file system and their enablement state - (as reported by is-enabled). If one or more - PATTERNs are specified, only units whose filename - (just the last component of the path) matches one of them are shown. + List unit files installed on the system, in combination with their enablement state (as reported by + is-enabled). If one or more PATTERNs are specified, only unit + files whose name matches one of them are shown (patterns matching unit file system paths are not + supported). enable NAME... + enable PATH... - 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 of also - starting any of the units being enabled. If this - is desired, either should be used - together with this command, or an additional start - 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. - - This command will print the actions executed. This - output may be suppressed by passing . + Enable one or more units or unit instances. This will create a set of symlinks, as encoded in the + [Install] sections of the indicated unit files. After the symlinks have been created, + the system manager configuration is reloaded (in a way equivalent to daemon-reload), in + order to ensure the changes are taken into account immediately. Note that this does + not have the effect of also starting any of the units being enabled. If this is + desired, combine this command with the switch, or invoke start + with appropriate arguments later. Note that in case of unit instance enablement (i.e. enablement of units of + the form foo@bar.service), 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. + + This command expects either valid unit names (in which case appropriate unit files for these names + are automatically searched in the various unit file directories), or absolute paths to unit files (in which + case these files are read directly). If a specified unit file is located outside of the unit file + directories searched automatically, an additional symlink is created, linking it into the unit + configuration path, thus ensuring it is automatically found when requested by commands such as + start. + + This command will print the file system operations 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 the changes are taken into account. + Note that this operation creates only the symlinks suggested in the [Install] + 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 + daemon-reload manually as necessary, in order to ensure the 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, 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. - - Using enable on masked units - results in an error. + 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, + 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. + + Using enable on masked units is not supported and results in an error. @@ -1044,28 +1036,31 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service 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, either - should be used together with this command, or - an additional stop command should be executed - afterwards. - - This command will print the actions executed. This - output may be suppressed by passing . + 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 enable or + link. Note that this removes all symlinks to matching unit files, + including manually created symlinks, and not just those actually created by enable or + link. Note that while disable undoes the effect of + enable, the two commands are otherwise not symmetric, as disable may + remove more symlinks than a prior enable invocation of the same unit created. + + This command expects valid unit names only, it does not accept paths to unit files. + + In addition to the units specified as arguments, all units are disabled that are listed in the + Also= setting contained in the [Install] section of any of the unit + files being operated on. + + 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 switch, or invoke the stop command + with appropriate arguments later. + + This command will print information about the file system operations (symlink removals) + executed. This output may be suppressed by passing . - This command honors , - , and - in a similar way as - enable. + This command honors , , + and in a similar way as enable. @@ -1073,12 +1068,10 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service 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. + Reenable one or more units, as specified on the command line. This is a combination of + disable and enable and is useful to reset the symlinks a unit file is + enabled with to the defaults configured in its [Install] section. This commands expects + a unit uname only, it does not accept paths to unit files. @@ -1209,16 +1202,13 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service 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 enablement and manual - activation. Use this option with care. This honors the - option to only mask temporarily - until the next reboot of the system. The - option can be used to ensure that the units are also stopped. + Mask one or more units, as specified on the command line. This will link these unit files 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 enablement + and manual activation. Use this option with care. This honors the option to only + mask temporarily until the next reboot of the system. The 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. @@ -1226,23 +1216,20 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service unmask NAME... - Unmask one or more unit files, as specified on the - command line. This will undo the effect of - mask. + Unmask one or more unit files, as specified on the command line. This will undo the effect of + mask. This command expects valid unit names only, it does not accept unit file + paths. - link FILENAME... + link PATH... - 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 - is not installed directly in the unit search path. + 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 + disable. The effect of this command is that a unit file is made available for commands + such as start, even though it is not installed directly in the unit search path. diff --git a/src/systemctl/systemctl.c b/src/systemctl/systemctl.c index 5298fcfb9c..bfd770e4df 100644 --- a/src/systemctl/systemctl.c +++ b/src/systemctl/systemctl.c @@ -6533,7 +6533,7 @@ static void systemctl_help(void) { " unit is required or wanted\n\n" "Unit File Commands:\n" " list-unit-files [PATTERN...] List installed unit files\n" - " enable NAME... Enable one or more unit files\n" + " enable [NAME...|PATH...] Enable one or more unit files\n" " disable NAME... Disable one or more unit files\n" " reenable NAME... Reenable one or more unit files\n" " preset NAME... Enable/disable one or more unit files\n" -- cgit v1.2.3-54-g00ecf