Skip to content

Commit f785240

Browse files
eriksjolunderiksjolund
committed
Split examples into subdirectories
Create the configuration files that are written in README.md as separate files. These text chunks are thus duplicated which violates the DRY-principle (Don't repeat yourself). It would be good to avoid this duplication in the future, for instance by generating out HTML documentation in such a way that the configuration files are included. Signed-off-by: Erik Sjölund <[email protected]>
1 parent fb1ecd2 commit f785240

20 files changed

+611
-448
lines changed

‎README.md

Lines changed: 4 additions & 448 deletions
Large diffs are not rendered by default.

‎examples/example1/README.md

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
return to [main page](../..)
2+
3+
## Example 1
4+
5+
``` mermaid
6+
graph TB
7+
8+
a1[curl localhost:8080] -.->a2[nginx container in systemd user service]
9+
10+
```
11+
12+
Set up a systemd user service _example1.service_ for the user _test_ where rootless podman is running the container image __docker.io/library/nginx__.
13+
Configure _socket activation_ for TCP port 8080.
14+
15+
1. Log in to user _test_
16+
2. Create directories
17+
```
18+
$ mkdir -p $HOME/.config/systemd/user
19+
$ mkdir -p $HOME/.config/containers/systemd
20+
```
21+
3. Create a directory that will be bind-mounted to _/etc/nginx/conf.d_ in the container
22+
```
23+
$ mkdir $HOME/nginx_conf_d
24+
```
25+
4. Create the file _$HOME/nginx_conf_d/default.conf_ with the file contents
26+
```
27+
server {
28+
listen 8080;
29+
server_name localhost;
30+
location / {
31+
root /usr/share/nginx/html;
32+
index index.html index.htm;
33+
}
34+
error_page 500 502 503 504 /50x.html;
35+
location = /50x.html {
36+
root /usr/share/nginx/html;
37+
}
38+
}
39+
```
40+
The file contents were created with the command
41+
```
42+
podman run --rm -ti docker.io/library/nginx /bin/bash -c 'cat /etc/nginx/conf.d/default.conf | grep -v \# | sed "s/listen\s\+80;/listen 8080;/g" | sed /^[[:space:]]*$/d' > default.conf
43+
```
44+
5. Create the file _$HOME/.config/containers/systemd/example1.container_ with the file contents
45+
```
46+
[Unit]
47+
Requires=example1.socket
48+
After=example1.socket
49+
50+
[Container]
51+
Image=docker.io/library/nginx
52+
Environment=NGINX=3;
53+
Volume=%h/nginx_conf_d:/etc/nginx/conf.d:Z
54+
[Install]
55+
WantedBy=default.target
56+
```
57+
6. Optional step for improved security: Edit the file _$HOME/.config/containers/systemd/example1.container_
58+
and add this line below the line `[Container]`
59+
```
60+
Network=none
61+
```
62+
For details, see section [_Possibility to restrict the network in the container_](#possibility-to-restrict-the-network-in-the-container)
63+
7. Create the file _$HOME/.config/systemd/user/example1.socket_ that defines the sockets that the container should use
64+
```
65+
[Unit]
66+
Description=Example 1
67+
68+
[Socket]
69+
ListenStream=0.0.0.0:8080
70+
71+
[Install]
72+
WantedBy=sockets.target
73+
```
74+
8. Reload the systemd configuration
75+
```
76+
$ systemctl --user daemon-reload
77+
```
78+
9. Start the socket
79+
```
80+
$ systemctl --user start example1.socket
81+
```
82+
10. Test the web server
83+
```
84+
$ curl localhost:8080 | head -4
85+
<!DOCTYPE html>
86+
<html>
87+
<head>
88+
<title>Welcome to nginx!</title>
89+
```

‎examples/example1/default.conf

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
server {
2+
listen 8080;
3+
server_name localhost;
4+
location / {
5+
root /usr/share/nginx/html;
6+
index index.html index.htm;
7+
}
8+
error_page 500 502 503 504 /50x.html;
9+
location = /50x.html {
10+
root /usr/share/nginx/html;
11+
}
12+
}

‎examples/example1/example1.container

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
[Unit]
2+
Requires=example1.socket
3+
After=example1.socket
4+
5+
[Container]
6+
Image=docker.io/library/nginx
7+
Environment=NGINX=3;
8+
Volume=%h/nginx_conf_d:/etc/nginx/conf.d:Z
9+
[Install]
10+
WantedBy=default.target

‎examples/example1/example1.socket

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
[Unit]
2+
Description=Example 1
3+
4+
[Socket]
5+
ListenStream=0.0.0.0:8080
6+
7+
[Install]
8+
WantedBy=sockets.target

‎examples/example2/README.md

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
return to [main page](../..)
2+
3+
## Example 2
4+
5+
``` mermaid
6+
graph TB
7+
8+
a1[curl localhost:80] -.->a2[nginx container in systemd system service]
9+
10+
```
11+
12+
Set up a systemd system service _example2.service_ where rootful podman is running the container image __docker.io/library/nginx__.
13+
Configure _socket activation_ for TCP port 80.
14+
15+
The instructions are similar to Example 1.
16+
17+
1. Create the file _/etc/containers/systemd/example2.container_ with the file contents
18+
```
19+
[Unit]
20+
Requires=example2.socket
21+
After=example2.socket
22+
23+
[Container]
24+
Image=docker.io/library/nginx
25+
Environment=NGINX=3;
26+
[Install]
27+
WantedBy=default.target
28+
```
29+
2. Optional step for improved security: Edit the file _/etc/containers/systemd/example2.container_
30+
and add this line below the line `[Container]`
31+
```
32+
Network=none
33+
```
34+
For details, see section [_Possibility to restrict the network in the container_](#possibility-to-restrict-the-network-in-the-container)
35+
3. Create the file _/etc/systemd/system/example2.socket_ that defines the sockets that the container should use
36+
```
37+
[Unit]
38+
Description=Example 2
39+
40+
[Socket]
41+
ListenStream=0.0.0.0:80
42+
43+
[Install]
44+
WantedBy=sockets.target
45+
```
46+
4. Reload the systemd configuration
47+
```
48+
$ sudo systemctl daemon-reload
49+
```
50+
5. Start the socket
51+
```
52+
$ sudo systemctl start example2.socket
53+
```
54+
6. Test the web server
55+
```
56+
$ curl localhost:80 | head -4
57+
<!DOCTYPE html>
58+
<html>
59+
<head>
60+
<title>Welcome to nginx!</title>
61+
```

‎examples/example2/example2.container

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
[Unit]
2+
Requires=example2.socket
3+
After=example2.socket
4+
5+
[Container]
6+
Image=docker.io/library/nginx
7+
Environment=NGINX=3;
8+
[Install]
9+
WantedBy=default.target

‎examples/example2/example2.socket

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
[Unit]
2+
Description=Example 2
3+
4+
[Socket]
5+
ListenStream=0.0.0.0:80
6+
7+
[Install]
8+
WantedBy=sockets.target

‎examples/example3/README.md

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
return to [main page](../..)
2+
3+
## Example 3
4+
5+
status: experimental
6+
7+
``` mermaid
8+
graph TB
9+
10+
a1[curl localhost:80] -.->a2[nginx container in systemd system service with directive User=]
11+
12+
```
13+
14+
Set up a systemd system service _example3.service_ that is configured to run as the user _test_ (systemd configuration `User=test`)
15+
where rootless podman is running the container image __docker.io/library/nginx__.
16+
Configure _socket activation_ for TCP port 80.
17+
18+
The default configuration for _ip_unprivileged_port_start_ is used
19+
20+
```
21+
$ cat /proc/sys/net/ipv4/ip_unprivileged_port_start
22+
1024
23+
```
24+
25+
Unprivileged users are only able to listen on TCP port 1024 and higher.
26+
27+
The reason that the unprivileged user _test_ is able to run a socket-activated nginx container on port 80 is that
28+
the syscalls `socket()` and `bind()` were run by systemd manager (`systemd`) that is running as root.
29+
The socket file descriptor is then inherited by the rootless podman process.
30+
31+
Side-note: There is a [Podman feature request](https://github.com/containers/podman/discussions/20573)
32+
for adding Podman support for `User=` in systemd system services.
33+
The feature request was migrated into a GitHub discussion.
34+
35+
1. Create the user _test_ if it does not yet exist.
36+
```
37+
$ sudo useradd test
38+
```
39+
2. Check the UID of the user _test_
40+
```
41+
$ id -u test
42+
1000
43+
```
44+
3. Create the file _/etc/systemd/system/example3.service_ with the file contents
45+
```
46+
[Unit]
47+
Wants=network-online.target
48+
After=network-online.target
49+
[email protected]
50+
[email protected]
51+
RequiresMountsFor=/run/user/1000/containers
52+
53+
[Service]
54+
User=test
55+
Environment=PODMAN_SYSTEMD_UNIT=%n
56+
KillMode=mixed
57+
ExecStop=/usr/bin/podman rm -f -i --cidfile=/run/user/1000/%N.cid
58+
ExecStopPost=-/usr/bin/podman rm -f -i --cidfile=/run/user/1000/%N.cid
59+
Delegate=yes
60+
Type=notify
61+
NotifyAccess=all
62+
SyslogIdentifier=%N
63+
ExecStart=/usr/bin/podman run \
64+
--cidfile=/run/user/1000/%N.cid \
65+
--cgroups=split \
66+
--rm \
67+
--env "NGINX=3;" \
68+
-d \
69+
--replace \
70+
--name systemd-%N \
71+
--sdnotify=conmon \
72+
docker.io/library/nginx
73+
```
74+
(To adjust the file for your system, replace `1000` with the UID found in step 2)
75+
4. Optional step for improved security: Edit the file _/etc/systemd/system/example3.service_
76+
and add the option `--network none` to the `podman run` command.
77+
For details, see section [_Possibility to restrict the network in the container_](#possibility-to-restrict-the-network-in-the-container)
78+
5. Create the file _/etc/systemd/system/example3.socket_ with the file contents
79+
```
80+
[Unit]
81+
Description=Example 3 socket
82+
83+
[Socket]
84+
ListenStream=0.0.0.0:80
85+
86+
[Install]
87+
WantedBy=sockets.target
88+
```
89+
6. Reload the systemd configuration
90+
```
91+
$ sudo systemctl daemon-reload
92+
```
93+
7. Start the socket
94+
```
95+
$ sudo systemctl start example3.socket
96+
```
97+
8. Test the web server
98+
```
99+
$ curl localhost:80 | head -4
100+
<!DOCTYPE html>
101+
<html>
102+
<head>
103+
<title>Welcome to nginx!</title>
104+
```

‎examples/example3/example3.service

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
[Unit]
2+
Wants=network-online.target
3+
After=network-online.target
4+
Requires[email protected]
5+
After[email protected]
6+
RequiresMountsFor=/run/user/1000/containers
7+
8+
[Service]
9+
User=test
10+
Environment=PODMAN_SYSTEMD_UNIT=%n
11+
KillMode=mixed
12+
ExecStop=/usr/bin/podman rm -f -i --cidfile=/run/user/1000/%N.cid
13+
ExecStopPost=-/usr/bin/podman rm -f -i --cidfile=/run/user/1000/%N.cid
14+
Delegate=yes
15+
Type=notify
16+
NotifyAccess=all
17+
SyslogIdentifier=%N
18+
ExecStart=/usr/bin/podman run \
19+
--cidfile=/run/user/1000/%N.cid \
20+
--cgroups=split \
21+
--rm \
22+
--env "NGINX=3;" \
23+
-d \
24+
--replace \
25+
--name systemd-%N \
26+
--sdnotify=conmon \
27+
docker.io/library/nginx

0 commit comments

Comments
 (0)