From e9d0d054456b43d61237e592b587c344364a7a61 Mon Sep 17 00:00:00 2001 From: Rodrigo Caballero Date: Fri, 16 Feb 2018 12:38:40 -0600 Subject: [PATCH 1/8] Add service restart concept. Signed-off-by: Rodrigo Caballero --- source/clear-linux/concepts/restart.rst | 232 ++++++++++++++++++++++++ 1 file changed, 232 insertions(+) create mode 100644 source/clear-linux/concepts/restart.rst diff --git a/source/clear-linux/concepts/restart.rst b/source/clear-linux/concepts/restart.rst new file mode 100644 index 00000000..fc0165c4 --- /dev/null +++ b/source/clear-linux/concepts/restart.rst @@ -0,0 +1,232 @@ +.. _cl-restart: + +Restarting system services after an OS update +############################################# + +The software life cycle describes how software is created, developed, and +deployed, but also includes how to replace or update software. A good OS +provides tools for the entire software life cycle. These tools must include +ways to remove software components properly when replaced with something else. + +Most of the work on software update code in |CL| has primarily focused on +adding new software to the system. Aside from recommending to users to reboot +their system once in a while to ensure the new software is running, we did not +provide any tools to do this easily, until now. + +User challenges +*************** + +Users might find it difficult to determine which services to restart. Users +can either evaluate each system and reboot manually, or figure out which +services to restart based on documentation like the |CL| Release Notes. +Since neither option solves the issue for many users, we established +improvement in this area was needed. + +Over the years, several OSes have approached the problem and come up with +partial solutions. Some solutions are based on three steps: + +#. Mark updates requiring a reboot, such as kernel updates. +#. Inform the user of those updates. +#. Ask usersto restart. + +Other variants automatically restart services during an upgrade. These +solutions are acceptable since there is nothing wrong with regularly +restarting services when your OS does not update automatically. Users are +already logged into a terminal, aware of updates happening, and ready to +respond to messages and notices about additional actions to take after an OS +update. + +However, |CL| updates software automatically and users never see any notices +from the updater. Users can still review the journal, which stores updater +notices. + +This scenario requires a completely different solution. Thus, we arrive at the +following solution requirements: + +* Eliminate the guesswork about what to restart and under what circumstances. +* Cannot restart everything. Many service deamons do not yet support an automatic + background restart. +* Fit into the |CL| architectural perspective: be small, quick, and lean. + +Enter :command:`clr-service-restart` +************************************ + +After exploring possible solutions, we devised a simple and efficient method +of catching the most typical reasons to restart a service daemon: + +* The new version replaced the executable file itself. +* The new version replaces a library component used by a service daemon. + +Both cases are extremely common. Thus, any solution that can detect these situations will provide good results for +our purposes. There are other cases to consider, for instance, when +configuration files or shared data files change on disk, but this is less +common. Our method focuses on restarting daemons when it is really needed, +especially in the case of security updates. + +The kernel actually provides us with this exact information in the +:file:`procfs` filesystem. Both the deleted executable file case and the +upgraded library component file case are detectable by reading +various files in the :file:`procfs` filesystem. + +The second part of the problem is to determine whether or not actual running +processes are part of a system service. The reason we're only interested +in system services is because that is where the risk is large for +security issues, and most system services are background tasks that +have no direct user interaction. We did not consider restarting things such +as desktop tasks because it would ruin any sort of user experience quickly. + +Fortunately, :command:`systemd` provides us with a simple way of determining +what tasks are active and entirely within the system domain, and we can +directly determine what service daemon they are part of. This approach +eliminates any daemon that is not started to begin with. + +The combination of these two partial solutions effectively gives us a nice +tool, with very little overhead, that shows which system daemons +are in need of a restart: + + Figure 1: Invoking :command:`clr-service-restart' to show all system + services in need of a restart + + .. code-block:: bash + + $ sudo clr-service-restart -a -n + + .. code-block:: console + + upower.service: needs a restart (a library dependency was updated) + /usr/bin/systemctl --no-ask-password try-restart upower.service + NetworkManager.service: needs a restart (a library dependency was + updated) + /usr/bin/systemctl --no-ask-password try-restart NetworkManager.service + .... + +Making it `safe` +**************** + +Now that we know exactly what daemons should be restarted, we can go +ahead and restart all of them, right? Not so fast! You definitely +don't want to do this automatically. Restarting the gdm.service automatically +on all the PCs in the office will not get you brownie points. + +Before doing the restart, we need some selection mechanism to figure out what +is OK to restart, and what is not. Since we want to restart the important +processes automatically and in the background, we want to be conservative +and start with low-risk daemons that we know are restartable without +any significant impact. So, we need a whitelist. + +We've implemented this whitelist in |CL| by making +:command:`clr-service-restart` a one-stop tool to manipulate this +whitelist. By default, the |CL| OS provides a basic set of whitelist entries +that permit :command:`clr-service-restart` +to perform automatic restarts of service daemons if they are whitelisted +already. On top of that, the system administrator can maintain +their own overlay customization of the whitelist, by allowing them to either +'allow' or 'disallow' restarting of system services as well. When a software +update occurs, the whitelist is consulted to see if a service daemon is +allowed to be restarted or not. + +This gives local administrators full control over the process. Either the +local administrator can turn restarting all off, or they can add more +services to the list if needed. + +Options for :command:`clr-service-restart` +========================================== + +The :option:`allow` option tells :command:`clr-service-restart` that on this +machine, the tallow daemon may be restarted automatically after an OS +software update. The :command:`clr-service-restart` daemon creates the +appropriate symlink in :file:`/etc/clr-service-restart` to keep a record +of this. + + .. code-block:: bash + + $ sudo clr-service-restart allow tallow.service + +The :option:`disallow` command tells :command:`clr-service-restart` that +although the OS defaults permit :option:`rngd` to be restarted, it should not +be done on this particular system. A symlink is created in +:file:`/etc/clr-service-restart` that points to :file:`/dev/null` to record +this. Note that you don't need to add the :option:'.service' part to refer to +the correct unit name. + + .. code-block:: bash + + $ sudo clr-service-restart disallow rngd + +The :option:`default` command makes :command:`clr-service-restart` revert +back to the OS provided defaults and delete any symlink in +:file:`/etc/clr-service-restart`. In the following example, it causes +:option:`rngd` to be restarted automatically again, because it is whitelisted +for automatic service restarts by default in |CL|. + + .. code-block:: bash + + $ sudo clr-service-restart default rngd + +Checking in on :command:`clr-service-restart` +********************************************* + +:command:`clr-service-restart` works in the background and is invoked by +:command:`swupd` automatically. The journal output shows +that services are being restarted once in a while after an OS software update. + +This still means that there are system services that are not being restarted, +so you may want check on the current situation and potentially take action. +To enable this, :command:`clr-service-restart` can be invoked with two +additional options, which are described below. + + :option:`-n` + +This option makes :command:`clr-service-restart` perform no restarts. Instead +it displays the services that could potentially be restarted. When used, +:command:`clr-service-restart` outputs a list of messages showing which +service needs a restart, what unit it is, and why it needs a restart. Also, +it shows the command that it would have used to restart this unit. + + :option:`-a` + +This option makes :command:`clr-service-restart` consider all system +services, not just the ones that are whitelisted. Because the default +whitelist in |CL| is relatively short at the moment, you may want to use this +option to restart everything that it can find when you log in on the system. + +Of course, if you pass both options (:option:`-a` and :option:`-n`), you will +see the complete list of system services that need a restart. This is +very handy to answer the question whether you may have missed restarting +another daemon or not, without actually doing this inadvertently. + +Telemetry +********* + +The |CL| team has attempted to minimize any disruption caused by this tool, +but we realize that it can cause problems, either in the form of a short +service outage when a daemon is being restarted, or worse, when a daemon +fails to properly restart. + +For that reason, we have created a whitelist to ensure units that we do not +trust to restart are left alone, however, if something bad does happen, we +want to have a way of catching it early. + +We've implemented this as follows: +If we find a unit that fails to automatically restart after an OS update, +and that unit resides in the system location :file:`/usr/lib/systemd/system`, +then we create a telemetry record and +send that record to the optional |CL| telemetry service. + +If you don't have the |CL| telemetrics bundle installed, nothing will happen +with this data - it is discarded. However, if you do have the +telemetrics bundle installed, and you opted in to send telemetry, then +the name of the system unit is sent to our telemetry service. This allows +us to quickly correct mistakes and remove services that are not as +safe to restart as we thought. + +Conclusion +********** + +As always, we enjoy coming up with simple and efficient solutions that make +our |CL| users' lives easier, and we love to share them with a bigger +audience. We've made a github project of :command:`clr-service-restart` and +you are invited to look at the code, share your thoughts, and work with us on +improving the project. You can find the project at: + + https://github.com/clearlinux/clr-service-restart \ No newline at end of file From 4d6bf8f2a62e1d9164ef5b3e2eeb3c3940620072 Mon Sep 17 00:00:00 2001 From: MCamp859 Date: Mon, 26 Feb 2018 11:59:01 -0500 Subject: [PATCH 2/8] Edited text for grammar, flow, and conciseness. Signed-off-by: MCamp859 --- source/clear-linux/concepts/restart.rst | 242 ++++++++++-------------- 1 file changed, 97 insertions(+), 145 deletions(-) diff --git a/source/clear-linux/concepts/restart.rst b/source/clear-linux/concepts/restart.rst index fc0165c4..fbe8f9bd 100644 --- a/source/clear-linux/concepts/restart.rst +++ b/source/clear-linux/concepts/restart.rst @@ -4,88 +4,68 @@ Restarting system services after an OS update ############################################# The software life cycle describes how software is created, developed, and -deployed, but also includes how to replace or update software. A good OS +deployed, and includes how to replace or update software. A good OS provides tools for the entire software life cycle. These tools must include ways to remove software components properly when replaced with something else. Most of the work on software update code in |CL| has primarily focused on -adding new software to the system. Aside from recommending to users to reboot -their system once in a while to ensure the new software is running, we did not -provide any tools to do this easily, until now. +adding new software to the system. We recommend that users reboot their system +once in a while, but we did not provide any tools to restart services easily, +until now. User challenges *************** -Users might find it difficult to determine which services to restart. Users -can either evaluate each system and reboot manually, or figure out which -services to restart based on documentation like the |CL| Release Notes. -Since neither option solves the issue for many users, we established -improvement in this area was needed. +It can be difficult to determine which services to restart. You can either +evaluate each system and reboot manually, or figure out which services to +restart based on documentation like the |CL| release notes. Since neither +option solves the issue completely, the |CL| team created a solution. -Over the years, several OSes have approached the problem and come up with -partial solutions. Some solutions are based on three steps: +Over the years, several OSes approached the problem and created partial +solutions such as the following: -#. Mark updates requiring a reboot, such as kernel updates. -#. Inform the user of those updates. -#. Ask usersto restart. +* Automatically restart services during an upgrade. +* Evaluate services using these steps: -Other variants automatically restart services during an upgrade. These -solutions are acceptable since there is nothing wrong with regularly -restarting services when your OS does not update automatically. Users are -already logged into a terminal, aware of updates happening, and ready to -respond to messages and notices about additional actions to take after an OS -update. + * Mark updates requiring a reboot, such as kernel updates. + * Inform the user of those updates. + * Ask the user to restart. -However, |CL| updates software automatically and users never see any notices -from the updater. Users can still review the journal, which stores updater -notices. +Both solutions are acceptable for many OSes. However, |CL| updates software +automatically and users do not see notices from the updater unless they review +the journal. -This scenario requires a completely different solution. Thus, we arrive at the -following solution requirements: +|CL| requires a completely different solution, with the following +requirements: * Eliminate the guesswork about what to restart and under what circumstances. -* Cannot restart everything. Many service deamons do not yet support an automatic +* Cannot restart everything. Many service daemons do not support an automatic background restart. * Fit into the |CL| architectural perspective: be small, quick, and lean. -Enter :command:`clr-service-restart` -************************************ +:command:`clr-service-restart` functionality +******************************************** -After exploring possible solutions, we devised a simple and efficient method -of catching the most typical reasons to restart a service daemon: +The most typical reasons to restart a service daemon include: -* The new version replaced the executable file itself. -* The new version replaces a library component used by a service daemon. +* A new version replaces the executable file itself. +* A new version replaces a library component used by a service daemon. -Both cases are extremely common. Thus, any solution that can detect these situations will provide good results for -our purposes. There are other cases to consider, for instance, when -configuration files or shared data files change on disk, but this is less -common. Our method focuses on restarting daemons when it is really needed, -especially in the case of security updates. +Our method restarts daemons for both cases by reading various files in the +:file:`procfs` filesystem provided by the kernel. -The kernel actually provides us with this exact information in the -:file:`procfs` filesystem. Both the deleted executable file case and the -upgraded library component file case are detectable by reading -various files in the :file:`procfs` filesystem. +The second part of the problem is to determine whether or not running +processes are part of a system service. (The tool focuses on system services +because most system services are background tasks with no direct user +interaction.) Fortunately, :command:`systemd` provides a simple way to: -The second part of the problem is to determine whether or not actual running -processes are part of a system service. The reason we're only interested -in system services is because that is where the risk is large for -security issues, and most system services are background tasks that -have no direct user interaction. We did not consider restarting things such -as desktop tasks because it would ruin any sort of user experience quickly. +* Determine which active tasks are within the system domain. +* Determine which service daemon maps to the task. -Fortunately, :command:`systemd` provides us with a simple way of determining -what tasks are active and entirely within the system domain, and we can -directly determine what service daemon they are part of. This approach -eliminates any daemon that is not started to begin with. +We combined both solutions into a low-overhead tool that shows which system +daemons need a restart, as shown below: -The combination of these two partial solutions effectively gives us a nice -tool, with very little overhead, that shows which system daemons -are in need of a restart: - - Figure 1: Invoking :command:`clr-service-restart' to show all system - services in need of a restart + Figure 1: Invoking :command:`clr-service-restart` .. code-block:: bash @@ -100,133 +80,105 @@ are in need of a restart: /usr/bin/systemctl --no-ask-password try-restart NetworkManager.service .... -Making it `safe` -**************** +:command:`clr-service-restart` implements a whitelist to identify which +daemons can be restarted. The system administrator maintains a customized +overlay of the default |CL| OS whitelist. When a software update occurs, +:command:`clr-service-restart` consults the whitelist to see if a service +daemon is allowed to be restarted or not. See the options section below for +details. -Now that we know exactly what daemons should be restarted, we can go -ahead and restart all of them, right? Not so fast! You definitely -don't want to do this automatically. Restarting the gdm.service automatically -on all the PCs in the office will not get you brownie points. - -Before doing the restart, we need some selection mechanism to figure out what -is OK to restart, and what is not. Since we want to restart the important -processes automatically and in the background, we want to be conservative -and start with low-risk daemons that we know are restartable without -any significant impact. So, we need a whitelist. - -We've implemented this whitelist in |CL| by making -:command:`clr-service-restart` a one-stop tool to manipulate this -whitelist. By default, the |CL| OS provides a basic set of whitelist entries -that permit :command:`clr-service-restart` -to perform automatic restarts of service daemons if they are whitelisted -already. On top of that, the system administrator can maintain -their own overlay customization of the whitelist, by allowing them to either -'allow' or 'disallow' restarting of system services as well. When a software -update occurs, the whitelist is consulted to see if a service daemon is -allowed to be restarted or not. - -This gives local administrators full control over the process. Either the -local administrator can turn restarting all off, or they can add more -services to the list if needed. Options for :command:`clr-service-restart` -========================================== +****************************************** -The :option:`allow` option tells :command:`clr-service-restart` that on this -machine, the tallow daemon may be restarted automatically after an OS -software update. The :command:`clr-service-restart` daemon creates the -appropriate symlink in :file:`/etc/clr-service-restart` to keep a record -of this. +The :option:`allow` option identifies a daemon to restart after an OS software +update. The :command:`clr-service-restart` daemon creates a symlink in +:file:`/etc/clr-service-restart` as a record. The example below tells +:command:`clr-service-restart` to restart the :option:`tallow` daemon after an +OS software update. .. code-block:: bash $ sudo clr-service-restart allow tallow.service -The :option:`disallow` command tells :command:`clr-service-restart` that -although the OS defaults permit :option:`rngd` to be restarted, it should not -be done on this particular system. A symlink is created in -:file:`/etc/clr-service-restart` that points to :file:`/dev/null` to record -this. Note that you don't need to add the :option:'.service' part to refer to -the correct unit name. +The :option:`disallow` option tells :command:`clr-service-restart` not to +restart the specified daemon even if the OS defaults permit the daemon to be +restarted. The :command:`clr-service-restart` daemon creates a symlink in +:file:`/etc/clr-service-restart` that points to :file:`/dev/null` as a record. +The example below tells :command:`clr-service-restart` not to restart the +:option:`rngd` daemon after an OS software update. .. code-block:: bash $ sudo clr-service-restart disallow rngd -The :option:`default` command makes :command:`clr-service-restart` revert -back to the OS provided defaults and delete any symlink in -:file:`/etc/clr-service-restart`. In the following example, it causes -:option:`rngd` to be restarted automatically again, because it is whitelisted -for automatic service restarts by default in |CL|. +The :option:`default` option makes :command:`clr-service-restart` revert back +to the OS defaults and delete any symlink in :file:`/etc/clr-service-restart`. +The example below tells :command:`clr-service-restart` to restart +:option:`rngd` automatically again, because :option:`rngd` is whitelisted for +automatic service restarts by default in |CL|. .. code-block:: bash $ sudo clr-service-restart default rngd -Checking in on :command:`clr-service-restart` -********************************************* +Monitoring options for :command:`clr-service-restart` +===================================================== -:command:`clr-service-restart` works in the background and is invoked by -:command:`swupd` automatically. The journal output shows -that services are being restarted once in a while after an OS software update. +:command:`clr-service-restart` works in the background and is invoked with +:command:`swupd` automatically. You can review the journal output to verify +that services are restarted after an OS software update. -This still means that there are system services that are not being restarted, -so you may want check on the current situation and potentially take action. -To enable this, :command:`clr-service-restart` can be invoked with two -additional options, which are described below. +To monitor :command:`clr-service-restart` use one or both options described +below. :option:`-n` This option makes :command:`clr-service-restart` perform no restarts. Instead it displays the services that could potentially be restarted. When used, -:command:`clr-service-restart` outputs a list of messages showing which -service needs a restart, what unit it is, and why it needs a restart. Also, -it shows the command that it would have used to restart this unit. +:command:`clr-service-restart` outputs a list of messages showing: + +* Which service needs a restart. +* What unit it is. +* Why it needs a restart. +* Which command is required to restart this unit. :option:`-a` -This option makes :command:`clr-service-restart` consider all system -services, not just the ones that are whitelisted. Because the default -whitelist in |CL| is relatively short at the moment, you may want to use this -option to restart everything that it can find when you log in on the system. +This option makes :command:`clr-service-restart` consider all system services, +not only the ones that are whitelisted. Because the default whitelist in |CL| +is relatively short, you can use this option to restart all impacted services +when you log in on the system. + +If you pass both options (:option:`-a` and :option:`-n`), :command:`clr- +service-restart` displays a complete list of system services that need a +restart. Use both options to verify that all desired daemons have been +restarted. -Of course, if you pass both options (:option:`-a` and :option:`-n`), you will -see the complete list of system services that need a restart. This is -very handy to answer the question whether you may have missed restarting -another daemon or not, without actually doing this inadvertently. Telemetry ********* -The |CL| team has attempted to minimize any disruption caused by this tool, -but we realize that it can cause problems, either in the form of a short -service outage when a daemon is being restarted, or worse, when a daemon -fails to properly restart. +:command:`clr-service-restart` may cause problems such as a short service +outage when a daemon is being restarted, or if a daemon fails to properly +restart. To minimize issues, :command:`clr-service-restart` creates a +telemetry record and sends it to the optional |CL| telemetry service if both +conditions below are met: -For that reason, we have created a whitelist to ensure units that we do not -trust to restart are left alone, however, if something bad does happen, we -want to have a way of catching it early. +* If a unit fails to automatically restart after an OS update. +* If that unit resides in the system location :file:`/usr/lib/systemd/system`. -We've implemented this as follows: -If we find a unit that fails to automatically restart after an OS update, -and that unit resides in the system location :file:`/usr/lib/systemd/system`, -then we create a telemetry record and -send that record to the optional |CL| telemetry service. - -If you don't have the |CL| telemetrics bundle installed, nothing will happen -with this data - it is discarded. However, if you do have the -telemetrics bundle installed, and you opted in to send telemetry, then -the name of the system unit is sent to our telemetry service. This allows -us to quickly correct mistakes and remove services that are not as -safe to restart as we thought. +If you do not install the |CL| telemetrics bundle, the data is discarded. If +you install the telemetrics bundle and you opt to send telemetry, then the +system unit name is sent to the |CL| telemetry service. We evaluate the report +and update the whitelist to remove services that are not safe to restart. Conclusion ********** -As always, we enjoy coming up with simple and efficient solutions that make -our |CL| users' lives easier, and we love to share them with a bigger -audience. We've made a github project of :command:`clr-service-restart` and -you are invited to look at the code, share your thoughts, and work with us on -improving the project. You can find the project at: +The |CL| team enjoys coming up with simple and efficient solutions to make +your work easier. We made a github project of :command:`clr-service-restart` +and we invite you to look at the code, share your thoughts, and work with us +on improving the project. You can find the project at: https://github.com/clearlinux/clr-service-restart \ No newline at end of file From 15417d6999b6b5319fb183c0481b9002b8b60ef8 Mon Sep 17 00:00:00 2001 From: MCamp859 Date: Thu, 1 Mar 2018 15:47:19 -0500 Subject: [PATCH 3/8] Deleted prompt in examples. Signed-off-by: MCamp859 --- source/clear-linux/concepts/restart.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/clear-linux/concepts/restart.rst b/source/clear-linux/concepts/restart.rst index fbe8f9bd..1c6bfdc2 100644 --- a/source/clear-linux/concepts/restart.rst +++ b/source/clear-linux/concepts/restart.rst @@ -69,7 +69,7 @@ daemons need a restart, as shown below: .. code-block:: bash - $ sudo clr-service-restart -a -n + sudo clr-service-restart -a -n .. code-block:: console @@ -99,7 +99,7 @@ OS software update. .. code-block:: bash - $ sudo clr-service-restart allow tallow.service + sudo clr-service-restart allow tallow.service The :option:`disallow` option tells :command:`clr-service-restart` not to restart the specified daemon even if the OS defaults permit the daemon to be @@ -110,7 +110,7 @@ The example below tells :command:`clr-service-restart` not to restart the .. code-block:: bash - $ sudo clr-service-restart disallow rngd + sudo clr-service-restart disallow rngd The :option:`default` option makes :command:`clr-service-restart` revert back to the OS defaults and delete any symlink in :file:`/etc/clr-service-restart`. @@ -120,7 +120,7 @@ automatic service restarts by default in |CL|. .. code-block:: bash - $ sudo clr-service-restart default rngd + sudo clr-service-restart default rngd Monitoring options for :command:`clr-service-restart` ===================================================== From 2e8a607a34f690516fc497529e541807e09d53f7 Mon Sep 17 00:00:00 2001 From: MCamp859 Date: Mon, 19 Mar 2018 17:27:16 -0400 Subject: [PATCH 4/8] More edits to restart concept. Deleted gerunds from section heads. Added period to figure caption. Signed-off-by: MCamp859 --- source/clear-linux/concepts/restart.rst | 44 ++++++++++++------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/source/clear-linux/concepts/restart.rst b/source/clear-linux/concepts/restart.rst index 1c6bfdc2..00c3f5cc 100644 --- a/source/clear-linux/concepts/restart.rst +++ b/source/clear-linux/concepts/restart.rst @@ -1,7 +1,7 @@ .. _cl-restart: -Restarting system services after an OS update -############################################# +Restart system services after an OS update +########################################## The software life cycle describes how software is created, developed, and deployed, and includes how to replace or update software. A good OS @@ -16,7 +16,7 @@ until now. User challenges *************** -It can be difficult to determine which services to restart. You can either +It is difficult to determine which services to restart. You can either evaluate each system and reboot manually, or figure out which services to restart based on documentation like the |CL| release notes. Since neither option solves the issue completely, the |CL| team created a solution. @@ -46,7 +46,7 @@ requirements: :command:`clr-service-restart` functionality ******************************************** -The most typical reasons to restart a service daemon include: +Typical reasons to restart a service daemon include: * A new version replaces the executable file itself. * A new version replaces a library component used by a service daemon. @@ -55,21 +55,21 @@ Our method restarts daemons for both cases by reading various files in the :file:`procfs` filesystem provided by the kernel. The second part of the problem is to determine whether or not running -processes are part of a system service. (The tool focuses on system services +processes are part of a system service. The tool focuses on system services because most system services are background tasks with no direct user -interaction.) Fortunately, :command:`systemd` provides a simple way to: +interaction. Fortunately, :command:`systemd` provides a simple way to: * Determine which active tasks are within the system domain. * Determine which service daemon maps to the task. We combined both solutions into a low-overhead tool that shows which system -daemons need a restart, as shown below: +daemons require a restart, as shown below: - Figure 1: Invoking :command:`clr-service-restart` + Figure 1: Invoke :command:`clr-service-restart`. .. code-block:: bash - sudo clr-service-restart -a -n + sudo clr-service-restart -a -n .. code-block:: console @@ -99,7 +99,7 @@ OS software update. .. code-block:: bash - sudo clr-service-restart allow tallow.service + sudo clr-service-restart allow tallow.service The :option:`disallow` option tells :command:`clr-service-restart` not to restart the specified daemon even if the OS defaults permit the daemon to be @@ -110,7 +110,7 @@ The example below tells :command:`clr-service-restart` not to restart the .. code-block:: bash - sudo clr-service-restart disallow rngd + sudo clr-service-restart disallow rngd The :option:`default` option makes :command:`clr-service-restart` revert back to the OS defaults and delete any symlink in :file:`/etc/clr-service-restart`. @@ -120,16 +120,16 @@ automatic service restarts by default in |CL|. .. code-block:: bash - sudo clr-service-restart default rngd + sudo clr-service-restart default rngd -Monitoring options for :command:`clr-service-restart` -===================================================== +Monitor options for :command:`clr-service-restart` +================================================== :command:`clr-service-restart` works in the background and is invoked with -:command:`swupd` automatically. You can review the journal output to verify -that services are restarted after an OS software update. +:command:`swupd` automatically. Review the journal output to verify that +services are restarted after an OS software update. -To monitor :command:`clr-service-restart` use one or both options described +To monitor :command:`clr-service-restart`, use one or both options described below. :option:`-n` @@ -141,7 +141,7 @@ it displays the services that could potentially be restarted. When used, * Which service needs a restart. * What unit it is. * Why it needs a restart. -* Which command is required to restart this unit. +* Which command is required to restart the unit. :option:`-a` @@ -150,10 +150,10 @@ not only the ones that are whitelisted. Because the default whitelist in |CL| is relatively short, you can use this option to restart all impacted services when you log in on the system. -If you pass both options (:option:`-a` and :option:`-n`), :command:`clr- -service-restart` displays a complete list of system services that need a -restart. Use both options to verify that all desired daemons have been -restarted. +If you pass both options (:option:`-a` and :option:`-n`), +:command:`clr-service-restart` displays a complete list of system services +that require a restart. Use both options to verify that all desired daemons +are restarted. Telemetry From 850ac305c7ed14fe633f3cff90d850ff647868d5 Mon Sep 17 00:00:00 2001 From: user135711 <31940582+user135711@users.noreply.github.com> Date: Mon, 2 Apr 2018 19:21:13 -0700 Subject: [PATCH 5/8] Added note to increase size of VM partition I added a note that might confuse new users when following the getting started sequence download, import vmware VM->enable user space. The linux error will not indicate that the hard drive isn't big enough. The link did not render in the preview for some reason so edit it to conform with your relative links convention and build before pulling. --- source/clear-linux/guides/maintenance/enable-user-space.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/source/clear-linux/guides/maintenance/enable-user-space.rst b/source/clear-linux/guides/maintenance/enable-user-space.rst index e3a706bc..f5e9a1a8 100644 --- a/source/clear-linux/guides/maintenance/enable-user-space.rst +++ b/source/clear-linux/guides/maintenance/enable-user-space.rst @@ -97,6 +97,9 @@ To be able to execute all applications with root privileges, we must add the Install a GUI to test sudo -------------------------- +If you are following this sequence after just setting up the preconfigured +VMware virtual machine from the repo, you must [increase](./increase-virtual-disk-size#id1) +the virtual disk size or the following step will fail. To test the :command:`sudo` command and ensure it is set up correctly, install the Gnome Desktop Manager (gdm) and start it. From ece2cbab300fc01d043c7f58f15714ba26ca431d Mon Sep 17 00:00:00 2001 From: MCamp859 Date: Wed, 4 Apr 2018 17:56:13 -0400 Subject: [PATCH 6/8] Incorporated review feedback in restart concept. Signed-off-by: MCamp859 --- source/clear-linux/concepts/restart.rst | 78 ++++++++++++------------- 1 file changed, 39 insertions(+), 39 deletions(-) diff --git a/source/clear-linux/concepts/restart.rst b/source/clear-linux/concepts/restart.rst index 00c3f5cc..2b3e0fb7 100644 --- a/source/clear-linux/concepts/restart.rst +++ b/source/clear-linux/concepts/restart.rst @@ -8,10 +8,10 @@ deployed, and includes how to replace or update software. A good OS provides tools for the entire software life cycle. These tools must include ways to remove software components properly when replaced with something else. -Most of the work on software update code in |CL| has primarily focused on -adding new software to the system. We recommend that users reboot their system -once in a while, but we did not provide any tools to restart services easily, -until now. +Most of the work on software update code in |CL| was focused on adding new +software to the system. We recommended that users reboot their system once in +a while, but we did not provide any tools to restart services easily, until +now. User challenges *************** @@ -29,13 +29,11 @@ solutions such as the following: * Mark updates requiring a reboot, such as kernel updates. * Inform the user of those updates. - * Ask the user to restart. + * Ask the user to restart the OS. Both solutions are acceptable for many OSes. However, |CL| updates software automatically and users do not see notices from the updater unless they review -the journal. - -|CL| requires a completely different solution, with the following +the journal. |CL| requires a completely different solution, with the following requirements: * Eliminate the guesswork about what to restart and under what circumstances. @@ -43,16 +41,17 @@ requirements: background restart. * Fit into the |CL| architectural perspective: be small, quick, and lean. -:command:`clr-service-restart` functionality -******************************************** +clr-service-restart functionality +********************************* Typical reasons to restart a service daemon include: * A new version replaces the executable file itself. * A new version replaces a library component used by a service daemon. -Our method restarts daemons for both cases by reading various files in the -:file:`procfs` filesystem provided by the kernel. +Our method restarts daemons when it is really needed, especially +in the case of security updates. The tool restarts daemons by reading +various files in the :file:`procfs` filesystem provided by the kernel. The second part of the problem is to determine whether or not running processes are part of a system service. The tool focuses on system services @@ -60,36 +59,37 @@ because most system services are background tasks with no direct user interaction. Fortunately, :command:`systemd` provides a simple way to: * Determine which active tasks are within the system domain. -* Determine which service daemon maps to the task. +* Determine which tasks map to which service. We combined both solutions into a low-overhead tool that shows which system daemons require a restart, as shown below: - Figure 1: Invoke :command:`clr-service-restart`. +Figure 1: Invoke :command:`clr-service-restart`. - .. code-block:: bash +.. code-block:: bash - sudo clr-service-restart -a -n + sudo clr-service-restart -a -n - .. code-block:: console +.. code-block:: console - upower.service: needs a restart (a library dependency was updated) - /usr/bin/systemctl --no-ask-password try-restart upower.service - NetworkManager.service: needs a restart (a library dependency was - updated) - /usr/bin/systemctl --no-ask-password try-restart NetworkManager.service - .... + upower.service: needs a restart (a library dependency was updated) + /usr/bin/systemctl --no-ask-password try-restart upower.service + NetworkManager.service: needs a restart (a library dependency was + updated) + /usr/bin/systemctl --no-ask-password try-restart NetworkManager.service + .... :command:`clr-service-restart` implements a whitelist to identify which -daemons can be restarted. The system administrator maintains a customized -overlay of the default |CL| OS whitelist. When a software update occurs, +daemons can be restarted. The system administrator can customize the default +|CL| OS whitelist using :option:`allow` or :option:`disallow` options for +restarting system services. When a software update occurs, :command:`clr-service-restart` consults the whitelist to see if a service -daemon is allowed to be restarted or not. See the options section below for +daemon is allowed to be restarted or not. See the options section for details. -Options for :command:`clr-service-restart` -****************************************** +Options for clr-service-restart +******************************* The :option:`allow` option identifies a daemon to restart after an OS software update. The :command:`clr-service-restart` daemon creates a symlink in @@ -97,9 +97,9 @@ update. The :command:`clr-service-restart` daemon creates a symlink in :command:`clr-service-restart` to restart the :option:`tallow` daemon after an OS software update. - .. code-block:: bash +.. code-block:: bash - sudo clr-service-restart allow tallow.service + sudo clr-service-restart allow tallow.service The :option:`disallow` option tells :command:`clr-service-restart` not to restart the specified daemon even if the OS defaults permit the daemon to be @@ -108,9 +108,9 @@ restarted. The :command:`clr-service-restart` daemon creates a symlink in The example below tells :command:`clr-service-restart` not to restart the :option:`rngd` daemon after an OS software update. - .. code-block:: bash +.. code-block:: bash - sudo clr-service-restart disallow rngd + sudo clr-service-restart disallow rngd The :option:`default` option makes :command:`clr-service-restart` revert back to the OS defaults and delete any symlink in :file:`/etc/clr-service-restart`. @@ -118,12 +118,12 @@ The example below tells :command:`clr-service-restart` to restart :option:`rngd` automatically again, because :option:`rngd` is whitelisted for automatic service restarts by default in |CL|. - .. code-block:: bash +.. code-block:: bash - sudo clr-service-restart default rngd + sudo clr-service-restart default rngd -Monitor options for :command:`clr-service-restart` -================================================== +Monitor options for clr-service-restart +======================================= :command:`clr-service-restart` works in the background and is invoked with :command:`swupd` automatically. Review the journal output to verify that @@ -132,7 +132,7 @@ services are restarted after an OS software update. To monitor :command:`clr-service-restart`, use one or both options described below. - :option:`-n` +:option:`-n` This option makes :command:`clr-service-restart` perform no restarts. Instead it displays the services that could potentially be restarted. When used, @@ -143,7 +143,7 @@ it displays the services that could potentially be restarted. When used, * Why it needs a restart. * Which command is required to restart the unit. - :option:`-a` +:option:`-a` This option makes :command:`clr-service-restart` consider all system services, not only the ones that are whitelisted. Because the default whitelist in |CL| @@ -181,4 +181,4 @@ your work easier. We made a github project of :command:`clr-service-restart` and we invite you to look at the code, share your thoughts, and work with us on improving the project. You can find the project at: - https://github.com/clearlinux/clr-service-restart \ No newline at end of file +https://github.com/clearlinux/clr-service-restart From ff6990efa55d8b54b886a603705fdcbc8dff6358 Mon Sep 17 00:00:00 2001 From: user135711 <31940582+user135711@users.noreply.github.com> Date: Thu, 5 Apr 2018 08:02:41 -0700 Subject: [PATCH 7/8] Corrected syntax --- .../clear-linux/guides/maintenance/enable-user-space.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/source/clear-linux/guides/maintenance/enable-user-space.rst b/source/clear-linux/guides/maintenance/enable-user-space.rst index f5e9a1a8..2ee3f111 100644 --- a/source/clear-linux/guides/maintenance/enable-user-space.rst +++ b/source/clear-linux/guides/maintenance/enable-user-space.rst @@ -97,9 +97,10 @@ To be able to execute all applications with root privileges, we must add the Install a GUI to test sudo -------------------------- -If you are following this sequence after just setting up the preconfigured -VMware virtual machine from the repo, you must [increase](./increase-virtual-disk-size#id1) -the virtual disk size or the following step will fail. +.. note:: +If you are following this sequence after just setting up the pre-configured VMware virtual machine from +the repo, you must :ref:increase virtual disk size or the following step +will fail. To test the :command:`sudo` command and ensure it is set up correctly, install the Gnome Desktop Manager (gdm) and start it. From d7f8576b27c4c6632a7328bac3ff085fe8233f18 Mon Sep 17 00:00:00 2001 From: user135711 <31940582+user135711@users.noreply.github.com> Date: Thu, 5 Apr 2018 08:09:38 -0700 Subject: [PATCH 8/8] Update enable-user-space.rst --- source/clear-linux/guides/maintenance/enable-user-space.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/clear-linux/guides/maintenance/enable-user-space.rst b/source/clear-linux/guides/maintenance/enable-user-space.rst index 2ee3f111..8f8e23d1 100644 --- a/source/clear-linux/guides/maintenance/enable-user-space.rst +++ b/source/clear-linux/guides/maintenance/enable-user-space.rst @@ -99,7 +99,7 @@ Install a GUI to test sudo -------------------------- .. note:: If you are following this sequence after just setting up the pre-configured VMware virtual machine from -the repo, you must :ref:increase virtual disk size or the following step +the repo, you must :ref:`increase virtual disk size` or the following step will fail. To test the :command:`sudo` command and ensure it is set up correctly,