add changelog for 1.13
[beanstalkd.git] / doc / beanstalkd.ronn
blob6404deddbc58730073673eef0cf223f9f61e7be5
1 beanstalkd(1) -- simple, fast work queue
2 ========================================
4 ## SYNOPSIS
6 `beanstalkd` [<options>]
8 ## DESCRIPTION
10 `Beanstalkd` is a simple work-queue service. Its interface is
11 generic, though it was originally designed for reducing the latency of
12 page views in high-volume web applications by running time-consuming
13 tasks asynchronously.
15 When started, `beanstalkd` opens a socket (or uses a file descriptor
16 provided by the init(1) system, see [ENVIRONMENT][]) and listens for
17 incoming connections. For each connection, it reads a sequence of
18 commands to create, reserve, delete, and otherwise manipulate "jobs",
19 units of work to be done. See file `doc/protocol.txt` in the
20 `beanstalkd` distribution for a thorough description of the meaning
21 and format of the `beanstalkd` protocol.
23 ## OPTIONS
25 * `-b` <path>:
26   Use a binlog to keep jobs on persistent storage in directory <path>.
27   Upon startup, `beanstalkd` will recover any binlog that is present
28   in <path>, then, during normal operation, append new jobs and
29   changes in state to the binlog.
31 * `-f` <ms>:
32   Call fsync(2) at most once every <ms> milliseconds. Larger values
33   for <ms> reduce disk activity and improve speed at the cost of
34   safety. A power failure could result in the loss of up to <ms>
35   milliseconds of history.
37   A <ms> value of 0 will cause `beanstalkd` to call fsync every time
38   it writes to the binlog.
40   The default behavior is to sync every 50 ms.
42   (This option has no effect without `-b`.)
44 * `-F`:
45   Never call fsync(2). Equivalent to `-f` with an infinite <ms> value.
47   (This option has no effect without `-b`.)
49 * `-h`:
50   Show a brief help message and exit.
52 * `-l` <addr>:
53   Listen on address <addr> (default is 0.0.0.0).
55   When <addr> starts with "unix:", the unprefixed value of it will be
56   used as the local filesystem path to create a UNIX socket instead of
57   a TCP socket. In this case the value of `-p` will be ignored.
59   (Option `-l` has no effect if sd-daemon(5) socket activation is
60   being used. See also [ENVIRONMENT][].)
62 * `-p` <port>:
63   Listen on TCP port <port> (default is 11300).
65   (Option `-p` has no effect if sd-daemon(5) socket activation is
66   being used. See also [ENVIRONMENT][].)
68 * `-s` <bytes>:
69   The size in bytes of each binlog file.
71   (This option has no effect without `-b`.)
73 * `-u` <user>:
74   Become the user <user> and its primary group.
76 * `-V`:
77   Increase verbosity. May be used more than once to produce more
78   verbose output. The output format is subject to change.
80 * `-v`:
81   Print the version string and exit.
83 * `-z` <bytes>:
84   The maximum size in bytes of a job.
86 * `-c`:
87   This flag has no effect. It is kept for historical compatibility only.
89 * `-n`:
90   This flag has no effect. It is kept for historical compatibility only.
92 ## ENVIRONMENT
94 * `LISTEN_PID`, `LISTEN_FDS`:
95   These variables can be set by init(1). See sd_listen_fds(3) for
96   details.
98 ## SEE ALSO
100 sd-daemon(3), sd_listen_fds(3)
102 Files `README.md` and `doc/protocol.txt` in the `beanstalkd`
103 distribution.
105 <https://beanstalkd.github.io/>
107 ## AUTHOR
109 `Beanstalkd` is written by Keith Rarick and maintained by the community at
110 <https://github.com/beanstalkd/beanstalkd/issues>