pid1
Do signal handling and orphan reaping for Unix PID1 init processes
https://github.com/fpco/pid1#readme
LTS Haskell 22.43: | 0.1.3.1 |
Stackage Nightly 2024-12-04: | 0.1.3.1 |
Latest on Hackage: | 0.1.3.1 |
pid1-0.1.3.1@sha256:f8ab0b221a2d484c4e1c5eed712600329fb1a45bb8c4f7d8c001c5ff30d068aa,1433
Module documentation for 0.1.3.1
- System
- System.Process
pid1
Do signal handling and orphan reaping for Unix PID1 init processes.
This provides a Haskell library, and an executable based on that library, for initializing signal handlers, spawning and child process, and reaping orphan processes. These are the responsibilities that must be fulfilled by the initial process in a Unix system, and in particular comes up when running Docker containers.
This library/executable will automatically detect if it is run as some process
besides PID1 and, if so, use a straightforward exec
system call instead.
NOTE This package is decidedly not portable, and will not work on Windows. If you have a use case where you think it makes sense to run on Windows, I’d be interested in hearing about it.
For a discussion on why this is useful, see this repo.
Usage
pid1 [-e|–env ENV] [-u|–user USER] [-g|–group GROUP] [-w|–workdir DIR] [-t|–timeout TIMEOUT] COMMAND [ARG1 ARG2 … ARGN]
Where:
-e
,--env
ENV
- Override environment variable from given name=value pair. Can be specified multiple times to set multiple environment variables.-u
,--user
USER
- The username the process will setuid before executing COMMAND-g
,--group
GROUP
- The group name the process will setgid before executing COMMAND-w
,--workdir
DIR
- chdir toDIR
before executing COMMAND-t
,--timeout
TIMEOUT
- timeout (in seconds) to wait for all child processes to exit (Default is 5 seconds)
WARNING
: by default pid1 will first send the TERM signal to it’s “immediate child” process.
In most scenarios that will be the only process running but in some cases that will be the
“main” process that could have spawned it’s own children. In this scenario it’s prudent to shutdown
the “main” process first, since usually it has mechanisms in place to shut down it’s children. If
we were to shutdown a child process before “main” was shutdown it might try to restart it.
This is why, if the “main” process doesn’t exit within timeout
we will proceed to send the TERM
signal to all processes and wait again for timeout
until we finally send the KILL signal to all
processes. This is a breaking change since 0.1.3.0.
The recommended use case for this executable is to embed it in a Docker image.
Assuming you’ve placed it at /sbin/pid1
, the two commonly recommended usages
are:
-
Override the entrypoint, either via
ENTRYPOINT
in your Dockerfile or--entrypoint
on the command line.docker run --rm --entrypoint /sbin/pid1 fpco/pid1 ps
-
Add
/sbin/pid1
to the beginning of your command.docker run --rm --entrypoint /usr/bin/env fpco/pid1 /sbin/pid1 ps
Docker images
You can find various docker images here. We usually target Ubuntu LTS as the parent image.
Changes
0.1.3.1
- Update to accomodate changes from latest process library. (
OpenExtHandle
). - Improve documentation related to timeout.
0.1.3.0
- By default pid1 will first send the TERM signal to it’s “immediate
child” process. In most scenarios that will be the only process
running but in some cases that will be the “main” process that could
have spawned it’s own children. In this scenario it’s prudent to
shutdown the “main” process first, since usually it has mechanisms in
place to shut down it’s children. If we were to shutdown a child
process before “main” was shutdown it might try to restart it. This
is why, if the “main” process doesn’t exit within
timeout
we will proceed to send the TERM signal to all processes and wait again fortimeout
until we finally send the KILL signal to all processes. This is a breaking change in 0.1.3.0.
0.1.2.0
- Removes support for ‘,’ separated list of environment variables
for
-e
command line option - Adds support for setting child processes wait timeout on SIGTERM or SIGINT
0.1.1.0
- Adds support for setuid and setguid when running command
- Adds support for setting current directory when running command
0.1.0.1
- Turn off all RTS options
0.1.0.0
- Initial release