diff --git a/README.md b/README.md index dc0fb3d..c7161bf 100644 --- a/README.md +++ b/README.md @@ -9,45 +9,41 @@ [crates-badge-exe]: https://img.shields.io/crates/v/pid1-exe.svg [crates-url-exe]: https://crates.io/crates/pid1-exe -A Rust library and binary for correct PID 1 signal handling and zombie -process reaping in containerized environments. +A Rust library and binary for correct PID 1 signal handling and zombie process reaping in containerized environments. ## Overview -In Unix-like systems, the process with Process ID (PID) 1 has special -responsibilities. It is the ancestor of all other processes and is -responsible for adopting orphaned processes and reaping them. When -running applications in containers, your application's process often -becomes PID 1. +In Unix-like systems, the process with Process ID (PID) 1 has special responsibilities. +It is the ancestor of all other processes and is responsible for adopting orphaned processes and reaping them. +When running applications in containers, your application's process often becomes PID 1. -Without proper handling, signals like `SIGTERM` might not be forwarded -to child processes, and zombie processes can accumulate, leading to -resource leaks. `pid1-rs` solves this by providing: +Without proper handling, signals like `SIGTERM` might not be forwarded to child processes, +and zombie processes can accumulate, leading to resource leaks. -- **Signal Forwarding:** Intercepts signals like `SIGTERM` and - `SIGINT` and forwards them to its child process, allowing for - graceful shutdown. -- **Zombie Reaping:** Acts as an init process to reap orphaned child - processes, preventing zombie process accumulation. +`pid1-rs` solves this by providing: +- **Graceful Shutdown:** Intercepts the signals `SIGTERM` and `SIGINT`, + forwarding them to the child process. If the child does not exit within + a configurable grace period (default: 2s), a `SIGKILL` is sent. +- **Zombie Reaping:** Acts as an init process to reap orphaned child processes, + preventing the accumulation of zombie processes. -This project provides two ways to use this functionality: as a Rust -library integrated into your application, or as a standalone binary -executable. +This project provides two ways to use this functionality: +- As a Rust library integrated into your application. +- As a standalone binary executable. ## Comparison with `tini` -[tini](https://github.com/krallin/tini) is a popular, minimal init for containers. `pid1-rs` -provides similar functionality with a different approach: +[`tini`](https://github.com/krallin/tini) is a popular, minimal init for containers. +`pid1-rs` provides similar functionality with a different approach: -- The **`pid1` library** integrates directly into your Rust - application. This is its main advantage over `tini`, as you don't - need to add a separate binary to your container. The PID 1 handling - logic is compiled into your application, simplifying your - `Dockerfile` and potentially reducing image size. -- The **`pid1-exe` binary** is a direct, Rust-native alternative to - `tini`. Both serve the same purpose as a standalone init binary. If - you prefer a toolchain built in Rust or need a init for non-Rust - applications, `pid1-exe` is an excellent choice. +- The **`pid1` library** integrates directly into your Rust application. + - This is its main advantage over `tini`, as you don't need to add a separate binary to your container. + - The PID 1 handling logic is compiled into your application, + simplifying your `Dockerfile` and potentially reducing image size. +- The **`pid1-exe` binary** is a direct Rust-native alternative to `tini`. + - Both serve the same purpose as a standalone init binary. + - If you prefer a toolchain built in Rust or need an init for non-Rust applications, + `pid1-exe` is an excellent choice. ## Packages in this Repository @@ -57,14 +53,13 @@ This repository consists of two packages: ## `pid1` Library Usage -This library is used to simplify Rust deployment in a containerized -environment. Instead of using binaries like [Haskell's pid1](https://github.com/fpco/pid1) or -[tini](https://github.com/krallin/tini) in your container, you can use this crate directly. +This library is used to simplify Rust deployment in a containerized environment. +Instead of using binaries like [Haskell's `pid1`](https://github.com/fpco/pid1) or +[`tini`](https://github.com/krallin/tini) in your container, you can use this crate directly. ### Usage -You must ensure that the `launch` method is the first statement in -your `main` function: +You must ensure that the `launch` method is the first statement in your `main` function: ``` rust use std::time::Duration; @@ -81,8 +76,7 @@ fn main() { } ``` -This function is meant only for Unix systems and the above code is a no-op -on Windows. +This function is meant only for Unix systems and the above code is a no-op on Windows. For more examples, see the [examples](./pid1/examples/) directory. @@ -93,13 +87,12 @@ it as the `ENTRYPOINT` in your container. ### Docker Example -In this example, `your-application` and its arguments are passed using -`CMD`. +In this example, `your-application` and its arguments are passed using `CMD`. -``` dockerfile -FROM alpine:3.14.2 +```dockerfile +FROM alpine -ADD --chmod=755 https://github.com/fpco/pid1-rs/releases/download/v0.1.0/pid1-x86_64-unknown-linux-musl /usr/bin/pid1 +ADD --chmod=755 https://github.com/fpco/pid1-rs/releases/download/v0.1.6/pid1-x86_64-unknown-linux-musl /usr/bin/pid1 ENTRYPOINT [ "pid1" ] CMD [ "your-application", "--arg1" ]