user/dev discussion of public-inbox itself
 help / color / mirror / Atom feed
747c14527851d0348ef700aff20553fb783d8b46 blob 4926 bytes (raw)

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
 
=head1 NAME

public-inbox-daemon - common usage for public-inbox network daemons

=head1 SYNOPSIS

	public-inbox-httpd
	public-inbox-nntpd

=head1 DESCRIPTION

This manual describes common options and behavior for
public-inbox network daemons.  Network daemons for public-inbox
provide read-only NNTP and HTTP access to public-inboxes.  Write
access to a public-inbox will never be required to run these.

These daemons are implemented with a common core using
non-blocking sockets and optimized for fairness; even with
thousands of connected clients over slow links.

They also provide graceful shutdown/upgrade support to avoid
breaking existing connections during software upgrades.

These daemons may also utilize multiple pre-forked worker
processes to take advantage of multiple CPUs.

=head1 OPTIONS

=over

=item -l, --listen ADDRESS

This takes an absolute path to a Unix socket or HOST:PORT
to listen on.  For example, to listen to TCP connections on
port 119, use: C<-l 0.0.0.0:119>.  This may also point to
a Unix socket (C<-l /path/to/http.sock>) for a reverse proxy
like L<nginx(8)> to use.

May be specified multiple times to allow listening on multiple
sockets.

This does not need to be specified at all if relying on
L<systemd.socket(5)> or similar

Default: server-dependent unless socket activation is used with
L<systemd(1)> or similar (see L<systemd.socket(5)>).

=item -1, --stdout PATH

Specify an appendable path to redirect stdout descriptor (1) to.
Using this is preferable to setting up the redirect externally
(e.g. E<gt>E<gt>/path/to/log in shell) since it allows
SIGUSR1 to be handled (see L<SIGNALS/SIGNALS> below).

Default: /dev/null

=item -2, --stderr PATH

Like C<--stdout>, but for the stderr descriptor (2).

=item -W, --worker-processes

Set the number of worker processes.

Normally, this should match the number of CPUs on the system to
take full advantage of the hardware.  However, users of
memory-constrained systems may want to lower this.

Setting this to zero (C<-W0>) disables the master/worker split;
saving some memory but removing the ability to use SIGTTIN
to increase worker processes or have the worker restarted by
the master on crashes.

Default: 1

=back

=head1 SIGNALS

Most of our signal handling behavior is copied from L<nginx(8)>
and/or L<starman(1)>; so it is possible to reuse common scripts
for managing them.

=over 8

=item SIGUSR1

Reopens log files pointed to by --stdout and --stderr options.

=item SIGUSR2

Spawn a new process with the intention to replace the running one.
See L</UPGRADING> below.

=item SIGHUP

Reload config files associated with the process.
(FIXME: not tested for -httpd, yet)

=item SIGTTIN

Increase the number of running workers processes by one.

=item SIGTTOU

Decrease the number of running worker processes by one.

=item SIGWINCH

Stop all running worker processes.   SIGHUP or SIGTTIN
may be used to restart workers.

=item SIGQUIT

Gracefully terminate the running process.

=back

SIGTTOU, SIGTTIN, SIGWINCH all have no effect when worker
processes are disabled with C<-W0> on the command-line.

=head1 ENVIRONMENT

=over 8

=item PI_CONFIG

The default config file, normally "~/.public-inbox/config".
See L<public-inbox-config(5)>

=item LISTEN_FDS, LISTEN_PID

Used by systemd (and compatible) installations for socket
activation.  See L<systemd.socket(5)> and L<sd_listen_fds(3)>.

=item PERL_INLINE_DIRECTORY

Pointing this to point to a writable directory enables the use
of L<Inline> and L<Inline::C> extensions which may provide
platform-specific performance improvements.  Currently, this
enables the use of L<vfork(2)> which speeds up subprocess
spawning with the Linux kernel.

public-inbox will never enable L<Inline::C> automatically without
this environment variable set or C<~/.cache/public-inbox/inline-c>
created by a user. See L<Inline> and L<Inline::C> for more details.

=back

=head1 UPGRADING

There are two ways to upgrade a running process.

Users of process management systems with socket activation
(L<systemd(1)> or similar) may rely on multiple instances For
systemd, this means using two (or more) '@' instances for each
service (e.g. C<SERVICENAME@INSTANCE>) as documented in
L<systemd.unit(5)>.

Users of traditional SysV init may use SIGUSR2 to spawn
a replacement process and gracefully terminate the old
process using SIGQUIT.

In either case, the old process will not truncate running
responses; so responses to expensive requests do not get
interrupted and lost.

=head1 CONTACT

Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>

The mail archives are hosted at L<https://public-inbox.org/meta/>
and L<http://hjrcffqmbrq6wope.onion/meta/>

=head1 COPYRIGHT

Copyright 2013-2020 all contributors L<mailto:meta@public-inbox.org>

License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>

=head1 SEE ALSO

L<public-inbox-httpd(1)>, L<public-inbox-nntpd(1)>
debug log:

solving 747c1452 ...
found 747c1452 in https://80x24.org/public-inbox.git

user/dev discussion of public-inbox itself

This inbox may be cloned and mirrored by anyone:

	git clone --mirror https://public-inbox.org/meta
	git clone --mirror http://czquwvybam4bgbro.onion/meta
	git clone --mirror http://hjrcffqmbrq6wope.onion/meta
	git clone --mirror http://ou63pmih66umazou.onion/meta

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V1 meta meta/ https://public-inbox.org/meta \
		meta@public-inbox.org
	public-inbox-index meta

Example config snippet for mirrors.
Newsgroups are available over NNTP:
	nntp://news.public-inbox.org/inbox.comp.mail.public-inbox.meta
	nntp://ou63pmih66umazou.onion/inbox.comp.mail.public-inbox.meta
	nntp://czquwvybam4bgbro.onion/inbox.comp.mail.public-inbox.meta
	nntp://hjrcffqmbrq6wope.onion/inbox.comp.mail.public-inbox.meta
	nntp://news.gmane.io/gmane.mail.public-inbox.general
 note: .onion URLs require Tor: https://www.torproject.org/

code repositories for the project(s) associated with this inbox:

	https://80x24.org/public-inbox.git

AGPL code for this site: git clone https://public-inbox.org/public-inbox.git