github.com/pwn-term/docker@v0.0.0-20210616085119-6e977cce2565/tini/tpl/README.md.in (about) 1 <!-- 2 3 ##################################### 4 # THIS FILE IS AUTOGENERATED! # 5 # Edit ./tpl/README.md.in instead # 6 ##################################### 7 8 --> 9 10 11 Tini - A tiny but valid `init` for containers 12 ============================================= 13 14 [](https://travis-ci.org/krallin/tini) 15 16 Tini is the simplest `init` you could think of. 17 18 All Tini does is spawn a single child (Tini is meant to be run in a container), 19 and wait for it to exit all the while reaping zombies and performing 20 signal forwarding. 21 22 23 Why Tini? 24 --------- 25 26 Using Tini has several benefits: 27 28 - It protects you from software that accidentally creates zombie processes, 29 which can (over time!) starve your entire system for PIDs (and make it 30 unusable). 31 - It ensures that the *default signal handlers* work for the software you run 32 in your Docker image. For example, with Tini, `SIGTERM` properly terminates 33 your process even if you didn't explicitly install a signal handler for it. 34 - It does so completely transparently! Docker images that work without Tini 35 will work with Tini without any changes. 36 37 If you'd like more detail on why this is useful, review this issue discussion: 38 [What is advantage of Tini?][0]. 39 40 41 Using Tini 42 ---------- 43 44 *NOTE: If you are using Docker 1.13 or greater, Tini is included in Docker 45 itself. This includes all versions of Docker CE. To enable Tini, just [pass the 46 `--init` flag to `docker run`][5].* 47 48 *NOTE: There are [pre-built Docker images available for Tini][10]. If 49 you're currently using an Ubuntu or CentOS image as your base, you can use 50 one of those as a drop-in replacement.* 51 52 *NOTE: There are Tini packages for Alpine Linux and NixOS. See below for 53 installation instructions.* 54 55 Add Tini to your container, and make it executable. Then, just invoke Tini 56 and pass your program and its arguments as arguments to Tini. 57 58 In Docker, you will want to use an entrypoint so you don't have to remember 59 to manually invoke Tini: 60 61 # Add Tini 62 ENV TINI_VERSION v@tini_VERSION_MAJOR@.@tini_VERSION_MINOR@.@tini_VERSION_PATCH@ 63 ADD https://github.com/krallin/tini/releases/download/${TINI_VERSION}/tini /tini 64 RUN chmod +x /tini 65 ENTRYPOINT ["/tini", "--"] 66 67 # Run your program under Tini 68 CMD ["/your/program", "-and", "-its", "arguments"] 69 # or docker run your-image /your/program ... 70 71 Note that you *can* skip the `--` under certain conditions, but you might 72 as well always include it to be safe. If you see an error message that 73 looks like `tini: invalid option -- 'c'`, then you *need* to add the `--`. 74 75 Arguments for Tini itself should be passed like `-v` in the following example: 76 `/tini -v -- /your/program`. 77 78 *NOTE: The binary linked above is a 64-bit dynamically-linked binary.* 79 80 81 ### Signed binaries ### 82 83 The `tini` and `tini-static` binaries are signed using the key `595E85A6B1B4779EA4DAAEC70B588DFF0527A9B7`. 84 85 You can verify their signatures using `gpg` (which you may install using 86 your package manager): 87 88 ENV TINI_VERSION v@tini_VERSION_MAJOR@.@tini_VERSION_MINOR@.@tini_VERSION_PATCH@ 89 ADD https://github.com/krallin/tini/releases/download/${TINI_VERSION}/tini /tini 90 ADD https://github.com/krallin/tini/releases/download/${TINI_VERSION}/tini.asc /tini.asc 91 RUN gpg --batch --keyserver hkp://p80.pool.sks-keyservers.net:80 --recv-keys 595E85A6B1B4779EA4DAAEC70B588DFF0527A9B7 \ 92 && gpg --batch --verify /tini.asc /tini 93 94 95 ### Alpine Linux Package ### 96 97 On Alpine Linux, you can use the following command to install Tini: 98 99 RUN apk add --no-cache tini 100 # Tini is now available at /sbin/tini 101 ENTRYPOINT ["/sbin/tini", "--"] 102 103 104 ### NixOS ### 105 106 Using Nix, you can use the following command to install Tini: 107 108 nix-env --install tini 109 110 ### Other Platforms ### 111 112 ARM and 32-bit binaries are available! You can find the complete list of 113 available binaries under [the releases tab][11]. 114 115 116 Options 117 ------- 118 119 ### Verbosity ### 120 121 The `-v` argument can be used for extra verbose output (you can pass it up to 122 3 times, e.g. `-vvv`). 123 124 125 ### Subreaping ### 126 127 By default, Tini needs to run as PID 1 so that it can reap zombies (by 128 running as PID 1, zombies get re-parented to Tini). 129 130 If for some reason, you cannot run Tini as PID 1, you should register Tini as 131 a process subreaper instead (only in Linux >= 3.4), by either: 132 133 + Passing the `-s` argument to Tini (`tini -s -- ...`) 134 + Setting the environment variable `TINI_SUBREAPER` 135 (e.g. `export TINI_SUBREAPER=`). 136 137 This will ensure that zombies get re-parented to Tini despite Tini not running 138 as PID 1. 139 140 *NOTE: Tini will issue a warning if it detects that it isn't running as PID 1 141 and isn't registered as a subreaper. If you don't see a warning, you're fine.* 142 143 144 ### Remapping exit codes ### 145 146 Tini will reuse the child's exit code when exiting, but occasionally, this may 147 not be exactly what you want (e.g. if your child exits with 143 after receiving 148 SIGTERM). Notably, this can be an issue with Java apps. 149 150 In this case, you can use the `-e` flag to remap an arbitrary exit code to 0. 151 You can pass the flag multiple times if needed. 152 153 For example: 154 155 ``` 156 tini -e 143 -- ... 157 ``` 158 159 160 ### Process group killing ### 161 162 By default, Tini only kills its immediate child process. This can be 163 inconvenient if sending a signal to that process does not have the desired 164 effect. For example, if you do 165 166 docker run krallin/ubuntu-tini sh -c 'sleep 10' 167 168 and ctrl-C it, nothing happens: SIGINT is sent to the 'sh' process, 169 but that shell won't react to it while it is waiting for the 'sleep' 170 to finish. 171 172 With the `-g` option, Tini kills the child process group , so that 173 every process in the group gets the signal. This corresponds more 174 closely to what happens when you do ctrl-C etc. in a terminal: The 175 signal is sent to the foreground process group. 176 177 178 ### Parent Death Signal ### 179 180 Tini can set its parent death signal, which is the signal Tini should receive 181 when *its* parent exits. To set the parent death signal, use the `-p` flag with 182 the name of the signal Tini should receive when its parent exits: 183 184 ``` 185 tini -p SIGTERM -- ... 186 ``` 187 188 *NOTE: See [this PR discussion][12] to learn more about the parent death signal 189 and use cases.* 190 191 192 More 193 ---- 194 195 ### Existing Entrypoint ### 196 197 Tini can also be used with an existing entrypoint in your container! 198 199 Assuming your entrypoint was `/docker-entrypoint.sh`, then you would use: 200 201 ENTRYPOINT ["/tini", "--", "/docker-entrypoint.sh"] 202 203 204 ### Statically-Linked Version ### 205 206 Tini has very few dependencies (it only depends on libc), but if your 207 container fails to start, you might want to consider using the statically-built 208 version instead: 209 210 ADD https://github.com/krallin/tini/releases/download/${TINI_VERSION}/tini-static /tini 211 212 213 ### Size Considerations ### 214 215 Tini is a very small file (in the 10KB range), so it doesn't add much weight 216 to your container. 217 218 The statically-linked version is bigger, but still < 1M. 219 220 221 Building Tini 222 ------------- 223 224 If you'd rather not download the binary, you can build Tini by running 225 `cmake . && make`. 226 227 Before building, you probably also want to run: 228 229 export CFLAGS="-DPR_SET_CHILD_SUBREAPER=36 -DPR_GET_CHILD_SUBREAPER=37" 230 231 This ensure that even if you're building on a system that has old Linux Kernel 232 headers (< 3.4), Tini will be built with child subreaper support. This is 233 usually what you want if you're going to use Tini with Docker (if your host 234 Kernel supports Docker, it should also support child subreapers). 235 236 237 Understanding Tini 238 ------------------ 239 240 After spawning your process, Tini will wait for signals and forward those 241 to the child process, and periodically reap zombie processes that may be 242 created within your container. 243 244 When the "first" child process exits (`/your/program` in the examples above), 245 Tini exits as well, with the exit code of the child process (so you can 246 check your container's exit code to know whether the child exited 247 successfully). 248 249 250 Debugging 251 --------- 252 253 If something isn't working just like you expect, consider increasing the 254 verbosity level (up to 3): 255 256 tini -v -- bash -c 'exit 1' 257 tini -vv -- true 258 tini -vvv -- pwd 259 260 261 Authors 262 ======= 263 264 Maintainer: 265 266 + [Thomas Orozco][20] 267 268 Contributors: 269 270 + [Tianon Gravi][30] 271 + [David Wragg][31] 272 + [Michael Crosby][32] 273 + [Wyatt Preul][33] 274 + [Patrick Steinhardt][34] 275 276 Special thanks to: 277 278 + [Danilo Bürger][40] for packaging Tini for Alpine 279 + [Asko Soukka][41] for packaging Tini for Nix 280 281 282 [0]: https://github.com/krallin/tini/issues/8 283 [5]: https://docs.docker.com/engine/reference/commandline/run/ 284 [10]: https://github.com/krallin/tini-images 285 [11]: https://github.com/krallin/tini/releases 286 [12]: https://github.com/krallin/tini/pull/114 287 [20]: https://github.com/krallin/ 288 [30]: https://github.com/tianon 289 [31]: https://github.com/dpw 290 [32]: https://github.com/crosbymichael 291 [33]: https://github.com/geek 292 [34]: https://github.com/pks-t 293 [40]: https://github.com/danilobuerger 294 [41]: https://github.com/datakurre