1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
4
<link rel="stylesheet" href="style.css" type="text/css">
5
<meta content="text/html; charset=iso-8859-1" http-equiv="Content-Type">
6
<link rel="Start" href="index.html">
7
<link rel="previous" href="Netplex_advanced.html">
8
<link rel="next" href="Netshm.html">
9
<link rel="Up" href="index.html">
10
<link title="Index of types" rel=Appendix href="index_types.html">
11
<link title="Index of exceptions" rel=Appendix href="index_exceptions.html">
12
<link title="Index of values" rel=Appendix href="index_values.html">
13
<link title="Index of class attributes" rel=Appendix href="index_attributes.html">
14
<link title="Index of class methods" rel=Appendix href="index_methods.html">
15
<link title="Index of classes" rel=Appendix href="index_classes.html">
16
<link title="Index of class types" rel=Appendix href="index_class_types.html">
17
<link title="Index of modules" rel=Appendix href="index_modules.html">
18
<link title="Index of module types" rel=Appendix href="index_module_types.html">
19
<link title="Uq_gtk" rel="Chapter" href="Uq_gtk.html">
20
<link title="Uq_ssl" rel="Chapter" href="Uq_ssl.html">
21
<link title="Https_client" rel="Chapter" href="Https_client.html">
22
<link title="Uq_tcl" rel="Chapter" href="Uq_tcl.html">
23
<link title="Equeue" rel="Chapter" href="Equeue.html">
24
<link title="Unixqueue" rel="Chapter" href="Unixqueue.html">
25
<link title="Unixqueue_pollset" rel="Chapter" href="Unixqueue_pollset.html">
26
<link title="Unixqueue_select" rel="Chapter" href="Unixqueue_select.html">
27
<link title="Uq_resolver" rel="Chapter" href="Uq_resolver.html">
28
<link title="Uq_engines" rel="Chapter" href="Uq_engines.html">
29
<link title="Uq_socks5" rel="Chapter" href="Uq_socks5.html">
30
<link title="Uq_io" rel="Chapter" href="Uq_io.html">
31
<link title="Uq_lwt" rel="Chapter" href="Uq_lwt.html">
32
<link title="Uq_libevent" rel="Chapter" href="Uq_libevent.html">
33
<link title="Equeue_intro" rel="Chapter" href="Equeue_intro.html">
34
<link title="Netcamlbox" rel="Chapter" href="Netcamlbox.html">
35
<link title="Netcgi_apache" rel="Chapter" href="Netcgi_apache.html">
36
<link title="Netcgi_modtpl" rel="Chapter" href="Netcgi_modtpl.html">
37
<link title="Netcgi_plex" rel="Chapter" href="Netcgi_plex.html">
38
<link title="Netcgi_common" rel="Chapter" href="Netcgi_common.html">
39
<link title="Netcgi" rel="Chapter" href="Netcgi.html">
40
<link title="Netcgi_ajp" rel="Chapter" href="Netcgi_ajp.html">
41
<link title="Netcgi_scgi" rel="Chapter" href="Netcgi_scgi.html">
42
<link title="Netcgi_cgi" rel="Chapter" href="Netcgi_cgi.html">
43
<link title="Netcgi_fcgi" rel="Chapter" href="Netcgi_fcgi.html">
44
<link title="Netcgi_dbi" rel="Chapter" href="Netcgi_dbi.html">
45
<link title="Netcgi1_compat" rel="Chapter" href="Netcgi1_compat.html">
46
<link title="Netcgi_test" rel="Chapter" href="Netcgi_test.html">
47
<link title="Netcgi_porting" rel="Chapter" href="Netcgi_porting.html">
48
<link title="Http_client_conncache" rel="Chapter" href="Http_client_conncache.html">
49
<link title="Http_client" rel="Chapter" href="Http_client.html">
50
<link title="Telnet_client" rel="Chapter" href="Telnet_client.html">
51
<link title="Ftp_data_endpoint" rel="Chapter" href="Ftp_data_endpoint.html">
52
<link title="Ftp_client" rel="Chapter" href="Ftp_client.html">
53
<link title="Http_fs" rel="Chapter" href="Http_fs.html">
54
<link title="Ftp_fs" rel="Chapter" href="Ftp_fs.html">
55
<link title="Netclient_tut" rel="Chapter" href="Netclient_tut.html">
56
<link title="Netgssapi" rel="Chapter" href="Netgssapi.html">
57
<link title="Nethttpd_types" rel="Chapter" href="Nethttpd_types.html">
58
<link title="Nethttpd_kernel" rel="Chapter" href="Nethttpd_kernel.html">
59
<link title="Nethttpd_reactor" rel="Chapter" href="Nethttpd_reactor.html">
60
<link title="Nethttpd_engine" rel="Chapter" href="Nethttpd_engine.html">
61
<link title="Nethttpd_services" rel="Chapter" href="Nethttpd_services.html">
62
<link title="Nethttpd_plex" rel="Chapter" href="Nethttpd_plex.html">
63
<link title="Nethttpd_util" rel="Chapter" href="Nethttpd_util.html">
64
<link title="Nethttpd_intro" rel="Chapter" href="Nethttpd_intro.html">
65
<link title="Netmech_scram" rel="Chapter" href="Netmech_scram.html">
66
<link title="Netmech_scram_gssapi" rel="Chapter" href="Netmech_scram_gssapi.html">
67
<link title="Netmcore" rel="Chapter" href="Netmcore.html">
68
<link title="Netmcore_camlbox" rel="Chapter" href="Netmcore_camlbox.html">
69
<link title="Netmcore_mempool" rel="Chapter" href="Netmcore_mempool.html">
70
<link title="Netmcore_heap" rel="Chapter" href="Netmcore_heap.html">
71
<link title="Netmcore_ref" rel="Chapter" href="Netmcore_ref.html">
72
<link title="Netmcore_array" rel="Chapter" href="Netmcore_array.html">
73
<link title="Netmcore_sem" rel="Chapter" href="Netmcore_sem.html">
74
<link title="Netmcore_mutex" rel="Chapter" href="Netmcore_mutex.html">
75
<link title="Netmcore_condition" rel="Chapter" href="Netmcore_condition.html">
76
<link title="Netmcore_queue" rel="Chapter" href="Netmcore_queue.html">
77
<link title="Netmcore_buffer" rel="Chapter" href="Netmcore_buffer.html">
78
<link title="Netmcore_matrix" rel="Chapter" href="Netmcore_matrix.html">
79
<link title="Netmcore_hashtbl" rel="Chapter" href="Netmcore_hashtbl.html">
80
<link title="Netmcore_process" rel="Chapter" href="Netmcore_process.html">
81
<link title="Netmcore_tut" rel="Chapter" href="Netmcore_tut.html">
82
<link title="Netplex_types" rel="Chapter" href="Netplex_types.html">
83
<link title="Netplex_mp" rel="Chapter" href="Netplex_mp.html">
84
<link title="Netplex_mt" rel="Chapter" href="Netplex_mt.html">
85
<link title="Netplex_log" rel="Chapter" href="Netplex_log.html">
86
<link title="Netplex_controller" rel="Chapter" href="Netplex_controller.html">
87
<link title="Netplex_container" rel="Chapter" href="Netplex_container.html">
88
<link title="Netplex_sockserv" rel="Chapter" href="Netplex_sockserv.html">
89
<link title="Netplex_workload" rel="Chapter" href="Netplex_workload.html">
90
<link title="Netplex_main" rel="Chapter" href="Netplex_main.html">
91
<link title="Netplex_config" rel="Chapter" href="Netplex_config.html">
92
<link title="Netplex_kit" rel="Chapter" href="Netplex_kit.html">
93
<link title="Rpc_netplex" rel="Chapter" href="Rpc_netplex.html">
94
<link title="Netplex_cenv" rel="Chapter" href="Netplex_cenv.html">
95
<link title="Netplex_semaphore" rel="Chapter" href="Netplex_semaphore.html">
96
<link title="Netplex_sharedvar" rel="Chapter" href="Netplex_sharedvar.html">
97
<link title="Netplex_mutex" rel="Chapter" href="Netplex_mutex.html">
98
<link title="Netplex_encap" rel="Chapter" href="Netplex_encap.html">
99
<link title="Netplex_intro" rel="Chapter" href="Netplex_intro.html">
100
<link title="Netplex_advanced" rel="Chapter" href="Netplex_advanced.html">
101
<link title="Netplex_admin" rel="Chapter" href="Netplex_admin.html">
102
<link title="Netshm" rel="Chapter" href="Netshm.html">
103
<link title="Netshm_data" rel="Chapter" href="Netshm_data.html">
104
<link title="Netshm_hashtbl" rel="Chapter" href="Netshm_hashtbl.html">
105
<link title="Netshm_array" rel="Chapter" href="Netshm_array.html">
106
<link title="Netshm_intro" rel="Chapter" href="Netshm_intro.html">
107
<link title="Netconversion" rel="Chapter" href="Netconversion.html">
108
<link title="Netchannels" rel="Chapter" href="Netchannels.html">
109
<link title="Netstream" rel="Chapter" href="Netstream.html">
110
<link title="Mimestring" rel="Chapter" href="Mimestring.html">
111
<link title="Netmime" rel="Chapter" href="Netmime.html">
112
<link title="Netsendmail" rel="Chapter" href="Netsendmail.html">
113
<link title="Neturl" rel="Chapter" href="Neturl.html">
114
<link title="Netaddress" rel="Chapter" href="Netaddress.html">
115
<link title="Netbuffer" rel="Chapter" href="Netbuffer.html">
116
<link title="Netdate" rel="Chapter" href="Netdate.html">
117
<link title="Netencoding" rel="Chapter" href="Netencoding.html">
118
<link title="Netulex" rel="Chapter" href="Netulex.html">
119
<link title="Netaccel" rel="Chapter" href="Netaccel.html">
120
<link title="Netaccel_link" rel="Chapter" href="Netaccel_link.html">
121
<link title="Nethtml" rel="Chapter" href="Nethtml.html">
122
<link title="Netstring_str" rel="Chapter" href="Netstring_str.html">
123
<link title="Netstring_pcre" rel="Chapter" href="Netstring_pcre.html">
124
<link title="Netmappings" rel="Chapter" href="Netmappings.html">
125
<link title="Netaux" rel="Chapter" href="Netaux.html">
126
<link title="Nethttp" rel="Chapter" href="Nethttp.html">
127
<link title="Netpagebuffer" rel="Chapter" href="Netpagebuffer.html">
128
<link title="Netfs" rel="Chapter" href="Netfs.html">
129
<link title="Netglob" rel="Chapter" href="Netglob.html">
130
<link title="Netauth" rel="Chapter" href="Netauth.html">
131
<link title="Netsockaddr" rel="Chapter" href="Netsockaddr.html">
132
<link title="Netnumber" rel="Chapter" href="Netnumber.html">
133
<link title="Rtypes" rel="Chapter" href="Rtypes.html">
134
<link title="Xdr_mstring" rel="Chapter" href="Xdr_mstring.html">
135
<link title="Xdr" rel="Chapter" href="Xdr.html">
136
<link title="Netcompression" rel="Chapter" href="Netcompression.html">
137
<link title="Netchannels_tut" rel="Chapter" href="Netchannels_tut.html">
138
<link title="Netmime_tut" rel="Chapter" href="Netmime_tut.html">
139
<link title="Netsendmail_tut" rel="Chapter" href="Netsendmail_tut.html">
140
<link title="Netulex_tut" rel="Chapter" href="Netulex_tut.html">
141
<link title="Neturl_tut" rel="Chapter" href="Neturl_tut.html">
142
<link title="Netsys" rel="Chapter" href="Netsys.html">
143
<link title="Netsys_posix" rel="Chapter" href="Netsys_posix.html">
144
<link title="Netsys_pollset" rel="Chapter" href="Netsys_pollset.html">
145
<link title="Netlog" rel="Chapter" href="Netlog.html">
146
<link title="Netexn" rel="Chapter" href="Netexn.html">
147
<link title="Netsys_win32" rel="Chapter" href="Netsys_win32.html">
148
<link title="Netsys_pollset_posix" rel="Chapter" href="Netsys_pollset_posix.html">
149
<link title="Netsys_pollset_win32" rel="Chapter" href="Netsys_pollset_win32.html">
150
<link title="Netsys_pollset_generic" rel="Chapter" href="Netsys_pollset_generic.html">
151
<link title="Netsys_signal" rel="Chapter" href="Netsys_signal.html">
152
<link title="Netsys_oothr" rel="Chapter" href="Netsys_oothr.html">
153
<link title="Netsys_xdr" rel="Chapter" href="Netsys_xdr.html">
154
<link title="Netsys_rng" rel="Chapter" href="Netsys_rng.html">
155
<link title="Netsys_types" rel="Chapter" href="Netsys_types.html">
156
<link title="Netsys_mem" rel="Chapter" href="Netsys_mem.html">
157
<link title="Netsys_tmp" rel="Chapter" href="Netsys_tmp.html">
158
<link title="Netgzip" rel="Chapter" href="Netgzip.html">
159
<link title="Netpop" rel="Chapter" href="Netpop.html">
160
<link title="Rpc_auth_dh" rel="Chapter" href="Rpc_auth_dh.html">
161
<link title="Rpc_key_service" rel="Chapter" href="Rpc_key_service.html">
162
<link title="Rpc_time" rel="Chapter" href="Rpc_time.html">
163
<link title="Rpc_auth_local" rel="Chapter" href="Rpc_auth_local.html">
164
<link title="Rpc_ssl" rel="Chapter" href="Rpc_ssl.html">
165
<link title="Rpc_xti_client" rel="Chapter" href="Rpc_xti_client.html">
166
<link title="Rpc" rel="Chapter" href="Rpc.html">
167
<link title="Rpc_program" rel="Chapter" href="Rpc_program.html">
168
<link title="Rpc_util" rel="Chapter" href="Rpc_util.html">
169
<link title="Rpc_portmapper_aux" rel="Chapter" href="Rpc_portmapper_aux.html">
170
<link title="Rpc_packer" rel="Chapter" href="Rpc_packer.html">
171
<link title="Rpc_transport" rel="Chapter" href="Rpc_transport.html">
172
<link title="Rpc_client" rel="Chapter" href="Rpc_client.html">
173
<link title="Rpc_simple_client" rel="Chapter" href="Rpc_simple_client.html">
174
<link title="Rpc_portmapper_clnt" rel="Chapter" href="Rpc_portmapper_clnt.html">
175
<link title="Rpc_portmapper" rel="Chapter" href="Rpc_portmapper.html">
176
<link title="Rpc_server" rel="Chapter" href="Rpc_server.html">
177
<link title="Rpc_auth_sys" rel="Chapter" href="Rpc_auth_sys.html">
178
<link title="Rpc_auth_gssapi" rel="Chapter" href="Rpc_auth_gssapi.html">
179
<link title="Rpc_proxy" rel="Chapter" href="Rpc_proxy.html">
180
<link title="Rpc_intro" rel="Chapter" href="Rpc_intro.html">
181
<link title="Rpc_mapping_ref" rel="Chapter" href="Rpc_mapping_ref.html">
182
<link title="Rpc_intro_gss" rel="Chapter" href="Rpc_intro_gss.html">
183
<link title="Shell_sys" rel="Chapter" href="Shell_sys.html">
184
<link title="Shell" rel="Chapter" href="Shell.html">
185
<link title="Shell_uq" rel="Chapter" href="Shell_uq.html">
186
<link title="Shell_fs" rel="Chapter" href="Shell_fs.html">
187
<link title="Shell_intro" rel="Chapter" href="Shell_intro.html">
188
<link title="Netsmtp" rel="Chapter" href="Netsmtp.html">
189
<link title="Intro" rel="Chapter" href="Intro.html">
190
<link title="Platform" rel="Chapter" href="Platform.html">
191
<link title="Foreword" rel="Chapter" href="Foreword.html">
192
<link title="Ipv6" rel="Chapter" href="Ipv6.html"><link title="Netplex Administration Guide" rel="Section" href="#main">
193
<link title="Configuration" rel="Section" href="#config">
194
<link title="The netplex-admin command" rel="Section" href="#admin">
195
<link title="How to configure log file rotation" rel="Section" href="#logrotate">
196
<link title="Configuration: The controller section" rel="Subsection" href="#controller">
197
<link title="Configuration: The service section" rel="Subsection" href="#service">
198
<link title="Configuration: The workload_manager section" rel="Subsection" href="#workload">
199
<title>Ocamlnet 3 Reference Manual : Netplex_admin</title>
202
<div class="navbar"><a href="Netplex_advanced.html">Previous</a>
203
<a href="index.html">Up</a>
204
<a href="Netshm.html">Next</a>
206
<center><h1>Netplex_admin</h1></center>
209
<span id="main"><h1>Netplex Administration Guide</h1></span>
212
Applications created with the Netplex framework all share the
213
following configuration settings and allow some basic
214
administration commands. This is only a common minimum - the
215
applications typically define more than this.
218
<span id="config"><h1>Configuration</h1></span>
221
The Netplex config file has the following layout:
224
<pre><code class="code">netplex {
225
controller { <settings> }; (* only one controller section *)
226
service { <settings> }; (* as many service sections as running services *)
228
service { <settings> };
229
(* The application can define further types of sections *)
234
<span id="controller"><h2>Configuration: The <code class="code">controller</code> section</h2></span>
237
This section configures the controller component. The task of the
238
controller is to start the containers for the workload, and logging.
241
<pre><code class="code">netplex {
243
socket_directory = "<path>";
244
max_level = "<debuglevel>";
245
logging { <settings> }; (* several logging destinations possible *)
247
logging { <settings> };
255
<li><code class="code">socket_directory</code>: The Netplex framework needs a directory where to
256
create Unix domain sockets. These sockets are needed for communication
257
between the started containers. If omitted, the directory defaults to
258
<code class="code">/tmp/.netplex</code>. It is not allowed that several running Netplex instances
259
share these directories, and hence it is strongly recommended to change
260
this default. If the path is not absolute, it is made absolute by
261
prepending the path of the working directory at the time Netplex
262
is started (usually the program start). Note that the paths of
263
Unix domain sockets are limited to 107 bytes for historic reasons,
264
so the <code class="code">socket_directory</code> should not be put too deeply into the
266
<li><code class="code">max_level</code>: This can be set to globally limit the log level. Defaults
267
to "debug", i.e. no maximum.</li>
270
Log levels are (same as for syslog):<ul>
281
Every <code class="code">logging</code> section defines a logging destination. Log messages
282
are written to all destinations that do not filter the messages out.
283
There are several types of <code class="code">logging</code> sections:
286
<span id="logerr"><h3>Logging to stderr</h3></span>
289
This type writes log messages to stderr:
292
<pre><code class="code">netplex {
295
type = "stderr"; (* mandatory *)
296
format = "<format string>"; (* optional *)
297
component = "<name_of_component>"; (* optional *)
298
subchannel = "<name_of_subchannel>"; (* optional *)
299
max_level = "<max_level>"; (* optional *)
308
The settings <code class="code">format</code>, <code class="code">component</code>, <code class="code">subchannel</code>, and <code class="code">max_level</code> may also
309
occur in the other types of logging definitions, and are explained below.
312
<span id="logfile"><h3>Logging to a file</h3></span>
315
This writes the log messages to a single file.
318
<pre><code class="code">netplex {
321
type = "file"; (* mandatory *)
322
file = "<path>"; (* mandatory *)
323
format = "<format string>"; (* optional *)
324
component = "<name_of_component>"; (* optional *)
325
subchannel = "<name_of_subchannel>"; (* optional *)
326
max_level = "<max_level>"; (* optional *)
336
<li><code class="code">file</code>: The file to which the messages are appended. If not existing,
337
the file is created. The file path must be absolute.</li>
340
The settings <code class="code">format</code>, <code class="code">component</code>, <code class="code">subchannel</code>, and <code class="code">max_level</code> may also
341
occur in the other types of logging definitions, and are explained below.
344
<span id="logmfile"><h3>Logging to multiple files</h3></span>
347
This logging definition directs to create several files in a common
351
<pre><code class="code">netplex {
354
type = "multi_file"; (* mandatory *)
355
directory = "<path>"; (* mandatory *)
356
format = "<format string>"; (* optional *)
357
file { <settings> };
359
file { <settings> };
368
The settings in the <code class="code">file</code> section:
371
<pre><code class="code"> file {
372
file = "<name>"; (* mandatory *)
373
format = "<format string>"; (* optional *)
374
component = "<name_of_component>"; (* optional *)
375
subchannel = "<name_of_subchannel>"; (* optional *)
376
max_level = "<max_level>"; (* optional *)
382
<li><code class="code">directory</code>: The absolute path of the directory where to create
383
the log files managed by the <code class="code">file</code> subsections</li>
384
<li><code class="code">file</code>: The name of the file in this directory</li>
387
The settings <code class="code">format</code>, <code class="code">component</code>, <code class="code">subchannel</code>, and <code class="code">max_level</code> may also
388
occur in the other types of logging definitions, and are explained below.
389
Note that a <code class="code">format</code> setting in the <code class="code">file</code> section overrides the
390
definition in <code class="code">logging</code> for the respective file.
393
<span id="logsys"><h3>Logging to syslog</h3></span>
396
The log messages are sent to the syslog device of the system
400
<pre><code class="code">netplex {
403
type = "syslog"; (* mandatory *)
404
identifier = "<identifier>"; (* optional *)
405
facility = "<facility>"; (* optional *)
406
format = "<format string>"; (* optional *)
407
component = "<name_of_component>"; (* optional *)
408
subchannel = "<name_of_subchannel>"; (* optional *)
409
max_level = "<max_level>"; (* optional *)
419
<li><code class="code">identifier</code>: A string prefixing each message. Default: empty.</li>
420
<li><code class="code">facility</code>: The syslog facility name. Defaults to "default".</li>
429
<li>local0 to local7</li>
439
<span id="logcommon"><h3>Common settings in <code class="code">logging</code></h3></span>
442
<b><code class="code">format</code>:</b> This parameter defines how the log messages look like.
443
This is a string containing variables in dollar notation (<code class="code">$name</code> or
444
<code class="code">${name}</code>). The following variable specifications are defined:
447
<li><code class="code">timestamp</code>: the time in standard format</li>
448
<li><code class="code">timestamp:<format></code> the time in custom format where <code class="code"><format></code> is a
449
<a href="Netdate.html"><code class="code">Netdate</code></a> format string</li>
450
<li><code class="code">timestamp:unix</code>: the time in seconds since the epoch</li>
451
<li><code class="code">component</code>: the name of the component emitting the log message</li>
452
<li><code class="code">subchannel</code>: the name of the subchannel</li>
453
<li><code class="code">level</code>: the log level</li>
454
<li><code class="code">message</code>: the log message</li>
457
The standard format string is
458
<pre><code class="code"> [${timestamp}] [${component}] [${level}] ${message} </code></pre>
461
<b><code class="code">component</code>:</b> This parameter filters messages by the component
462
emitting the messages. The component name is here the Netplex
463
service name, i.e. the <code class="code">name</code> parameter in the <code class="code">service</code> section
464
(see below). The parameter may be set to the component name, or
465
to a pattern matching component names. The wildcard <code class="code">*</code> can be used
469
Default: <code class="code">*</code>
472
<b><code class="code">subchannel</code>:</b> Netplex allows it to have several log channels per
473
component. There is normally only the main log channel, but components
474
can define additional channels. For example, a web server may have
475
a separate log channel for access logging. This parameter filters
476
messages by the subchannel identifier. Again it is possible to use
477
the wildcard <code class="code">*</code>.
480
The main log channel has the empty string as subchannel identifier,
481
hence <code class="code">subchannel=""</code> restricts the messages to the main channel.
484
Default: <code class="code">*</code>
487
<b><code class="code">max_level</code>:</b> Restricts the log level of the printed messages.
488
See above for possible levels.
491
<span id="3_Examplesforloggingdefinitions"><h3>Examples for logging definitions</h3></span>
494
1. Write everything to stderr:
497
<pre><code class="code"> logging { type="stderr" }
501
2. Write a separate file for each log level:
504
<pre><code class="code"> logging {
506
directory = "/var/log/myapp";
509
file = "all_debug.log";
513
file = "all_info.log";
515
... (* and so on ... *)
518
file = "all_emerg.log";
524
3. Write errors to syslog, but write access logs to a file:
527
<pre><code class="code"> logging {
530
subchannel = ""; (* i.e. only the main log channel goes here *)
534
file = "/var/log/myapp/access.log";
535
subchannel = "access";
540
<span id="service"><h2>Configuration: The <code class="code">service</code> section</h2></span>
543
Each service section instructs Netplex to start containers for the
544
service. If a service type is only defined by the application, but
545
does not appear in the config file, no containers will be started!
548
A service section looks like:
551
<pre><code class="code">netplex {
553
name = "<name>"; (* mandatory *)
554
user = "<user>"; (* optional *)
555
group = "<group>"; (* optional *)
556
startup_timeout = <float>; (* optional *)
557
conn_limit = <int>; (* optional *)
558
gc_when_idle = <bool>; (* optional *)
559
protocol { <settings> }; (* at least one *)
561
protocol { <settings> }; (* at least one *)
562
processor { <settings> }; (* mandatory *)
563
workload_manager { <settings> }; (* mandatory *)
570
The <code class="code">name</code> of the service is a freely chosen identifier. It is used
571
to reference the service, e.g. in log messages.
574
Each <code class="code">protocol</code> section defines a set of sockets with common
575
properties. The idea here is that a service may define several
576
protocols for accessing it, e.g. an HTTP-based protocol and an
577
RPC-based protocol. For each protocol there can then be several
581
The <code class="code">processor</code> section is the connection to the application
582
which must have defined the type of processor that is referenced
583
here. The task of the processor is to accept incoming connections
587
The <code class="code">workload_manager</code> section defines how many containers (i.e.
588
subprocesses or threads) are created for serving incoming connections.
592
<li><code class="code">user</code>: If the program is started as user <code class="code">root</code>, it is possible to
593
change the user for subprocesses. This parameter is the user name
594
for all subprocesses created for this service. This is only possible
595
when Netplex is running in the multi-processing mode, not in the
596
multi-threading mode. Default: do not change the user.</li>
597
<li><code class="code">group</code>: Same for the group</li>
598
<li><code class="code">startup_timeout</code>: If a subprocess does not start up within this
599
period of time, it is considered as dysfunctional, and killed again.
600
This misbehavior usually occurs because the initialization function
601
of the subprocess hangs.
602
This setting has only an effect in multi-processing mode.
603
Default: 60 seconds. A negative value turns this feature off.</li>
604
<li><code class="code">conn_limit</code>: If set, a container is automatically shut down if
605
it has processed this number of connections. This is sometimes
606
useful if there is a memory leak in the container, or memory is
607
not reclaimed quickly enough. Of course, one can only fight memory
608
problems in multi-processing mode this way. Default: no limit.</li>
609
<li><code class="code">gc_when_idle</code>: If <code class="code">true</code>, the Ocaml garbage collector is run
610
if a container is idle for one second.</li>
613
<span id="protocol"><h3>The <code class="code">protocol</code> subsection</h3></span>
619
<pre><code class="code">netplex {
622
name = "<protoname>"; (* mandatory *)
623
lstn_backlog = <int>; (* optional *)
624
lstn_reuseaddr = <bool>; (* optional *)
625
so_keepalive = <bool>; (* optional *)
626
tcp_nodelay = <bool>; (* optional *)
627
address { <settings> }; (* at least one *)
629
address { <settings> }; (* at least one *)
639
<li><code class="code">name</code>: The name of the protocol. This is an arbitrary identifier.
640
The name is passed to some hook functions.</li>
641
<li><code class="code">lstn_backlog</code>: The value of the backlog parameter of the <code class="code">listen</code>
642
system call. When a TCP connection is being accepted, the kernel does
643
this first on its own, and passes the accepted connection to the application
644
at the next opportunity (i.e. the <code class="code">accept</code> system call). Because of this
645
connections can queue up in the kernel, i.e. connections that are accepted
646
but not yet passed to the application. This parameter is the maximum
647
length of this queue. Note that there is usually also a kernel-defined
648
maximum (e.g. 128 on Linux). If you get spurious <code class="code">EAGAIN</code> errors
649
on the client side this might be an indication to increase this parameter.</li>
650
<li><code class="code">lstn_reuseaddr</code>: Whether to allow immediate reuse of socket addresses.
651
Defaults to <code class="code">true</code>.</li>
652
<li><code class="code">so_keepalive</code>: Whether to enable the TCP keep-alive feature which is
653
useful to detect unresponsive TCP connections (after a very long timeout
654
only, though). Defaults to <code class="code">false</code>.</li>
655
<li><code class="code">tcp_nodelay</code>: Whether to disable the Nagle algorithm for TCP. Normally,
656
TCP packets are minimally delayed before they are sent to the network
657
in the hope that the application makes more data available that could be
659
the same packet. Especially on local networks it is often not important
660
how many packets are really sent out, and by enabling this option
661
latencies can be, sometimes drastically, reduced. Defaults to <code class="code">false</code>.</li>
664
Specifying socket addresses:<ul>
665
<li><code class="code">address { type="internet"; bind="<ip>:<port>" }</code>: An IPv4 or IPv6
666
socket. The IP address can also given as host name which is looked up
667
at Netplex startup. Use <code class="code">0.0.0.0</code> as the IPv4 catch-all address. IPv6
668
addresses must be put into brackets. Use <code class="code">[:0]</code> as the IPv6 catch-all
670
<li><code class="code">address { type="local"; path="<path>" }</code>:
671
This is a OS-dependent default IPC mechanism for local
672
connections. On Unix, <code class="code">local</code> means Unix Domain sockets. On Win32,
673
<code class="code">local</code> means the <code class="code">w32_pipe_file</code> mechanism (see below). In <code class="code">path</code>, the name
674
of the Unix Domain socket or the file with the pipe name must be
676
<li><code class="code">address { type="unixdomain"; path="<path>" }</code>:
677
Unix domain sockets. In <code class="code">path</code> give the path.</li>
678
<li><code class="code">address { type="socket_file"; path="<path>" }</code>:
679
An emulation of Unix Domain sockets: A server socket
680
bound to <code class="code">127.0.0.1</code> and an anonymous port is used instead. The
681
port number is written to a file. The file must be given as <code class="code">path</code>.</li>
682
<li><code class="code">address { type="w32_pipe"; path="<path>" }</code>:
683
Win32 named pipes. The name of the pipe is given
684
as <code class="code">path</code>. This must be a name of the form "\\.\pipe\<name>".
685
The pipe server is configured so that only clients on the same
686
system can connect to it.</li>
687
<li><code class="code">address { type="w32_pipe_file"; path="<path>" }</code>:
688
An emulation of Unix Domain sockets: A named
689
pipe with an unpredictable random name is created instead. The
690
name of this pipe is written to the file given by <code class="code">path</code>.</li>
691
<li><code class="code">address { type="container" }</code>:
692
This special address causes that a separate <code class="code">local</code>
693
socket is created for each started container. The name of the
694
socket file is automatically chosen. The names of the socket
695
files can be queried with <a href="Netplex_cenv.html#VALlookup_container_sockets"><code class="code">Netplex_cenv.lookup_container_sockets</code></a>.
696
This type of socket is useful to control the load sent to each
697
container directly.</li>
700
<span id="processor"><h3>The <code class="code">processor</code> subsection</h3></span>
703
This section depends on the Netplex processor connected with it.
704
At minimum, this section has only a parameter <code class="code">type</code> that is the
705
name of a defined Netplex processor type:
708
<pre><code class="code">netplex {
711
type = "<type>";
712
... (* rest depends on the type *)
721
There are a number of processor types coming with Ocamlnet:
724
<li><a href="Rpc_netplex.html"><code class="code">Rpc_netplex</code></a>: RPC servers</li>
725
<li><a href="Netcgi_plex.html"><code class="code">Netcgi_plex</code></a>: Web connectors (e.g. FastCGI)</li>
726
<li><a href="Nethttpd_plex.html"><code class="code">Nethttpd_plex</code></a>: Web servers</li>
729
See these modules for how to configure the processors defined by them.
732
<span id="workload"><h2>Configuration: The <code class="code">workload_manager</code> section</h2></span>
735
The workload manager determines how many containers (processes or
736
threads) are running for each service.
739
<span id="constworkload"><h3>The constant workload manager</h3></span>
742
The constant workload manager starts a fixed number of containers.
743
If containers are shut down or crash, new containers are automatically
744
launched to replace the missing ones.
747
The config section looks like:
750
<pre><code class="code">netplex {
761
Note that the parameter <code class="code">threads</code> is also interpreted in
762
multi-processing mode (as number of processes).
765
<span id="dynworkload"><h3>The dynamic workload manager</h3></span>
768
The dynamic workload manager starts as many containers as needed to
769
handle the current load. Initially, a certain minimum number is started.
770
If it turns out that too many containers become busy, more containers
771
are started until a maximum is reached. If too many containers become
772
idle containers are shut down.
775
<pre><code class="code">netplex {
779
max_jobs_per_thread = <n>; (* optional, default: 1 *)
780
recommended_jobs_per_thread = <n>; (* optional *)
781
min_free_jobs_capacity = <n>; (* mandatory *)
782
max_free_jobs_capacity = <n>; (* mandatory *)
783
max_threads = <n>; (* mandatory *)
790
A thread is here a container, even in multi-processing mode. A job
791
is a TCP connection processed by a container. It is possible that
792
a container can process several jobs at the same time (but only a
793
few service types support this, e.g. RPC servers), and the whole
794
calculation is based on the job capacity, i.e. the number of jobs
795
all containers can execute in parallel.
798
The workload manager adjusts the number of containers so that there
799
is always free capacity for <code class="code">min_free_jobs_capacity</code>, but the free
800
capacity does not exceed <code class="code">max_free_jobs_capacity</code>. Also, the number
801
of containers is capped by <code class="code">max_threads</code>.
804
As mentioned, in most cases a container can only run one job at a
805
time (this is meant with <code class="code">max_jobs_per_thread=1</code>). Then
806
<code class="code">min_free_jobs_capacity</code> is just the minimum number of idle
807
containers, and <code class="code">max_free_jobs_capacity</code> the maximum number.
810
If more than one job can be executed, set <code class="code">max_jobs_per_thread</code> to
811
a value bigger than one. The workload manager assigns the components
812
then up to this number of TCP connections to process. A component
813
is filled up with jobs until it is full before jobs are assigned
814
to the next container.
817
The latter behavior can be modified by <code class="code">recommended_jobs_per_thread</code>.
818
This must be a number less than or equal to <code class="code">max_jobs_per_thread</code>,
819
and it means that the containers normally only get the recommended
820
number of jobs until they are "full", and only for very high workloads
821
this scheme is left, and even more jobs are assigned to the containers
822
until the maximum is reached. A common configuration is to set
823
<code class="code">recommended_jobs_per_thread=1</code>, so that each container gets first
824
only up to one job, and only if the maximum number of containers are
825
running, additional jobs can be assigned.
828
<span id="admin"><h1>The <code class="code">netplex-admin</code> command</h1></span>
831
Ocamlnet installs a little utility command <code class="code">netplex-admin</code> that can
832
be used to administer a <b>running</b> Netplex program.
835
<pre><code class="code">$ netplex-admin -help
836
Usage: netplex-admin [ options ] [ admin_cmd arg ... ]
837
-sockdir <dir> Set the socket directory of the Netplex to administer
838
-list List available Netplex services
839
-containers List available Netplex services with container details
840
-enable <name> Enable service <name>
841
-disable <name> Disable service <name>
842
-restart <name> Restart service <name>
843
-restart-all Restart all services
844
-shutdown Shutdown the whole Netplex
845
-reopen-logfiles Reopen logfiles (if possible)
846
-receiver <pat> Restrict receivers of admin messages to services matching <pat>
850
The <code class="code">-sockdir</code> argument should always be given, and the path is
851
the <code class="code">socket_directory</code> of the config file. If omitted, the socket
852
directory defaults to <code class="code">/tmp/.netplex</code>.
855
The <code class="code">-list</code> and <code class="code">-containers</code> switches allow it to get some introspection
856
into the running conglomerate of processes or threads. For <code class="code">-list</code>
857
the services and the socket addresses are printed. For <code class="code">-containers</code>
858
even more details are emitted, including the process IDs.
861
The <code class="code">-enable</code>, <code class="code">-disable</code>, and <code class="code">-restart</code> commands allow it to
862
manage the set of running services. A service can be disabled, which
863
means that all containers are shut down. Note that this does not mean
864
that incoming TCP connections are rejected. They are just not processed.
865
If enabled again, the containers are started again for the service,
866
and the processing of TCP connections is resumed (including the
867
connections that were accepted during the downtime). Disabling a
868
service is useful for temporarily stopping the service, e.g.
869
because it would interfer with other admin tasks.
872
A restart means to disable and re-enable the service. It may be
873
useful for cleanly reinitializing a service.
876
With <code class="code">-restart-all</code> even all services are restarted that are running
877
within the Netplex framework.
880
A <code class="code">-shutdown</code> starts the shutdown sequence. The shutdown is announced
881
to all containers, and in a second step, the containers are terminated.
882
Finally, the master process is also stopped.
885
The command <code class="code">-reopen-logfiles</code> is meaningful for all file-based
886
logging definitions. The current set of files is closed, and reopened
887
again. This is useful as post-action after log file rotation (see below).
890
<code class="code">netplex-admin</code> can also be used to send so-called admin messages to
891
the containers. These messages have a name and optionally arguments:
894
<pre><code class="code">$ netplex-admin ... name arg1 arg2 ...
898
Generally, the possible admin commands must be defined by the Netplex
899
processors. A few commands are defined by default, though:
902
<li><code class="code">netplex.threadlist</code>: Outputs information about threads and processes
904
<li><code class="code">netplex.logger.set_max_level <level></code>: Changes the maximum log level
905
to the level passed in the argument</li>
906
<li><code class="code">netplex.debug.enable <module></code>: Enables debug logging (as controlled
907
by <a href="Netlog.Debug.html"><code class="code">Netlog.Debug</code></a> for the module named in the argument. </li>
908
<li><code class="code">netplex.debug.disable <module></code>: Disables debug logging (as controlled
909
by <a href="Netlog.Debug.html"><code class="code">Netlog.Debug</code></a> for the module named in the argument. </li>
910
<li><code class="code">netplex.fd_table</code>: prints the file descriptor tracking table to
912
<li><code class="code">netplex.connections</code>: prints information about current TCP
913
connections to the log file</li>
914
<li><code class="code">netplex.mem.major</code>: triggers a major GC run</li>
915
<li><code class="code">netplex.mem.compact</code>: triggers a GC compaction</li>
916
<li><code class="code">netplex.mem.pools</code>: output information about Ocamlnet pools to
918
<li><code class="code">netplex.mem.stats</code>: output information about the memory managed by
919
the Ocaml runtime to the log file</li>
922
<span id="logrotate"><h1>How to configure log file rotation</h1></span>
925
<code class="code">logrotate</code> is a common utility to perform log file rotation. It can
926
be easily used together with Netplex. The essential point is to
927
run <code class="code">netplex-admin -reopen-logfiles</code> as post action to the rotation.
928
This stanza is an example how to configure the rotation in a
929
<code class="code">logrotate</code> config file:
932
<pre><code class="code">/var/log/myapp/file.log
939
/some/path/bin/netplex-admin \
940
-sockdir /var/lib/myapp/sockdir \
b'\\ No newline at end of file'
added
removed
doc/html-main/Netplex_admin.html
