
### Creating the Systemd Unit

Systemd is a process manager can start, stop, and manage processes ("_Units_") on boot or shutdown of your machine!
In this walkthrough, we'll be starting a long-running Node.js web server that lives in `/var/www/`.

To create a new _Unit_, we need to create a file in `/etc/systemd/system/` (the default location most Linux distributions).
This file should have the `.service` extension.

Let's create `/etc/systemd/system/webserver.service`:

```ini
[Unit]
# Since we're going to bind to a port on localhost, we need to wait for the
# network service to boot:
After=network.service
Description="My fancy web sever"

# Configure your long-running process:
# You'll want to adjust:
# * WorkingDirectory: change this to the directory your application is in
# * Environment: add or remove these options depending on your environment variable needs
# * ExecStart: this is the command that'll be run to start your application
[Service]
WorkingDirectory=/var/www # set the cwd (current working directory)
Environment=NODE_ENV="production"
Environment=PORT=3000
ExecStart=npm start # start your webserver! e.g. `node server.js`
Restart=always # always restart the webserver if it crashes
RestartSec=3 # after a crash, wait 3 seconds before restarting the server

# Run this service anytime the system boots:
[Install]
WantedBy=multi-user.target
```

After you've created the file, update it to have the correct permissions (`664`):

```bash
chmod 664 /etc/systemd/system/webserver.service
```

Don't be intimidated by the file above! A lot of it is boilerplate.
Read the comments placed in the above file to understand what each section is for!

You can learn more about the [_Unit_](https://www.freedesktop.org/software/systemd/man/systemd.unit.html) or [_Service_](https://www.freedesktop.org/software/systemd/man/systemd.service.html) sections in the systemd documentation.

The _Install_ section is used to configure when the service will start. Most commonly, you'll want `multi-user.target`.
The `WantedBy` value directly corresponds to different [Linux runlevels](https://en.wikipedia.org/wiki/Runlevel):

| runlevel | WantedBy value      | Description                                                            |
| -------- | ------------------- | ---------------------------------------------------------------------- |
| 0        | `poweroff.target`   | Run before the computer shuts down                                     |
| 1        | `rescue.target`     | Run when the system is in single-user mode                             |
| 2-4      | `multi-user.target` | Run when the system is ready for login, but before networking is setup |
| 5        | `graphical.target`  | Run when the display manager has started                               |
| 6        | `reboot.target`     | Run before the computer reboots                                        |

### Enabling the Systemd Unit

Now that the unit has been created, we need to reload the Systemd process.
This will allow Systemd to recognize the new file.

Run the following command:

```bash
systemctl daemon-reload
```

> **Tip**: You need to execute the above command to reload Systemd **every time** you edit your `.service` file(s).

Next, you'll need to enable the service. Running this command will create a symlink into your `WantedBy` target.

```bash
systemctl enable webserver
```

Finally, since your system is already booted, run the following command to start the service:

```bash
systemctl start webserver
```

### Cheatsheet

**Enabling (creating) or Disabling (deleting) your service**

```bash
systemctl enable webserver # install a new service file
systemctl disable webserver # uninstall a service file
```

**Starting, Restarting, or Stopping your service**

```bash
systemctl start webserver
systemctl restart webserver
systemctl stop webserver
```

**Checking the status of your service**

```bash
systemctl status webserver
```


Walkthrough: How to start a long-running command on boot with systemd

`xargs` reads space and line delimited strings from stdin and executes a specified command with the input as arguments.

This makes `xargs` a very powerful command when you want to run a command against arbitrary input.

For example, let's run the following command:

```bash
❯ echo 'hello    there\nbig         world' | xargs echo
```

`xargs` automatically parses `hello`, `there`, `big`, and `world` as individual inputs.
Then, these arguments are passed to the specified command (in this case, also `echo`).

```bash
❯ echo 'hello    there\nbig         world' | xargs echo

# What gets executed:
# echo 'hello' 'there' 'big' 'world'

# Output:
hello there big world
```

> **Note**: All computed input arguments were passed to a single `echo` command.

For more practical usage, you may find yourself wanting to run a command per single input line.
For example, when the command you're using doesn't support multiple arguments.

A common command I find this useful for is `aws s3`.
`aws s3` doesn't support passing multiple arguments, so each command may only accept a single bucket name.

For example, using brace expansion and `xargs` to pipe bucket names to `aws s3 rm` doesn't work:

```bash
❯ echo s3://my-bucket/partition-{1..3}/ | xargs aws s3 rm --recursive

# What gets executed:
# aws s3 rm --recursive 's3://my-bucket/partition-1/' 's3://my-bucket/partition-2/' 's3://my-bucket/partition-3/'

# Output:
Unknown options: s3://my-bucket/partition-2/,s3://my-bucket/partition-3/
```

To solve this, `xargs` accepts an `-n <number>` argument.
The `-n` argument configures how many arguments should be per command invocation (the default is `5000`).

So, since `aws s3 rm` only accepts one argument, we can pass `-n 1` to `xargs` to execute a single command per line:

```bash
❯ echo s3://my-bucket/partition-{1..3}/ | xargs -n 1 aws s3 rm --recursive

# What gets executed (sequentially):
# aws s3 rm --recursive 's3://my-bucket/partition-1/'
# aws s3 rm --recursive 's3://my-bucket/partition-2/'
# aws s3 rm --recursive 's3://my-bucket/partition-3/'

# Output:
success
success
success
```

> **Note**: The `aws s3 rm` command was invoked three times, once per input.

Success! 🎉

Now that we're running one command per line, it's important to note it's done so sequentially.
However, you may also want to parallelize execution of long-running commands.

`xargs` has an argument for parallelizing execution: `-P <number>`.

The above `aws s3 rm --recursive` example may take very long per parition, so we can maximize efficency by running all the commands at once.
To do this, we'll pass the `-P 3` argument:

```bash
❯ echo s3://my-bucket/partition-{1..3}/ | xargs -n 1 -P 3 aws s3 rm --recursive

# What gets executed (in parallel):
# aws s3 rm --recursive 's3://my-bucket/partition-1/'
# aws s3 rm --recursive 's3://my-bucket/partition-2/'
# aws s3 rm --recursive 's3://my-bucket/partition-3/'

# Output:
success
success
success
```

> **Tip**: To run one command per CPU, you can use this handy shortcut:
>
> ```bash
> xargs -n 1 -P $(getconf _NPROCESSORS_ONLN) command
> ```

Good luck! 🏎

timer.blog

Posts

Walkthrough: How to start a long-running command on boot with systemd

xargs(1), Shell Brace Expansion, and Single-Line Execution