doc/nghttpx.1

   1 .\" Man page generated from reStructuredText.
   2 .
   3 .TH "NGHTTPX" "1" "May 16, 2015" "1.0.0" "nghttp2"
   4 .SH NAME
   5 nghttpx \- HTTP/2 experimental proxy
   6 .
   7 .nr rst2man-indent-level 0
   8 .
   9 .de1 rstReportMargin
  10 \\$1 \\n[an-margin]
  11 level \\n[rst2man-indent-level]
  12 level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
  13 -
  14 \\n[rst2man-indent0]
  15 \\n[rst2man-indent1]
  16 \\n[rst2man-indent2]
  17 ..
  18 .de1 INDENT
  19 .\" .rstReportMargin pre:
  20 . RS \\$1
  21 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
  22 . nr rst2man-indent-level +1
  23 .\" .rstReportMargin post:
  24 ..
  25 .de UNINDENT
  26 . RE
  27 .\" indent \\n[an-margin]
  28 .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
  29 .nr rst2man-indent-level -1
  30 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
  31 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
  32 ..
  33 .SH SYNOPSIS
  34 .sp
  35 \fBnghttpx\fP [OPTIONS]... [<PRIVATE_KEY> <CERT>]
  36 .SH DESCRIPTION
  37 .sp
  38 A reverse proxy for HTTP/2, HTTP/1 and SPDY.
  39 .INDENT 0.0
  40 .TP
  41 .B <PRIVATE_KEY>
  42 Set path  to server\(aqs private key.   Required unless \fI\%\-p\fP,
  43 \fI\%\-\-client\fP or \fI\%\-\-frontend\-no\-tls\fP are given.
  44 .UNINDENT
  45 .INDENT 0.0
  46 .TP
  47 .B <CERT>
  48 Set path  to server\(aqs certificate.  Required  unless \fI\%\-p\fP,
  49 \fI\%\-\-client\fP or  \fI\%\-\-frontend\-no\-tls\fP are given.  To  make OCSP
  50 stapling work, this must be absolute path.
  51 .UNINDENT
  52 .SH OPTIONS
  53 .sp
  54 The options are categorized into several groups.
  55 .SS Connections
  56 .INDENT 0.0
  57 .TP
  58 .B \-b, \-\-backend=<HOST,PORT>
  59 Set  backend  host  and   port.   The  multiple  backend
  60 addresses are  accepted by repeating this  option.  UNIX
  61 domain socket  can be  specified by prefixing  path name
  62 with "unix:" (e.g., unix:/var/run/backend.sock)
  63 .sp
  64 Default: \fB127.0.0.1,80\fP
  65 .UNINDENT
  66 .INDENT 0.0
  67 .TP
  68 .B \-f, \-\-frontend=<HOST,PORT>
  69 Set  frontend  host and  port.   If  <HOST> is  \(aq*\(aq,  it
  70 assumes  all addresses  including  both  IPv4 and  IPv6.
  71 UNIX domain  socket can  be specified by  prefixing path
  72 name with "unix:" (e.g., unix:/var/run/nghttpx.sock)
  73 .sp
  74 Default: \fB*,3000\fP
  75 .UNINDENT
  76 .INDENT 0.0
  77 .TP
  78 .B \-\-backlog=<N>
  79 Set listen backlog size.
  80 .sp
  81 Default: \fB512\fP
  82 .UNINDENT
  83 .INDENT 0.0
  84 .TP
  85 .B \-\-backend\-ipv4
  86 Resolve backend hostname to IPv4 address only.
  87 .UNINDENT
  88 .INDENT 0.0
  89 .TP
  90 .B \-\-backend\-ipv6
  91 Resolve backend hostname to IPv6 address only.
  92 .UNINDENT
  93 .INDENT 0.0
  94 .TP
  95 .B \-\-backend\-http\-proxy\-uri=<URI>
  96 Specify      proxy       URI      in       the      form
  97 \fI\%http:/\fP/[<USER>:<PASS>@]<PROXY>:<PORT>.    If   a   proxy
  98 requires  authentication,  specify  <USER>  and  <PASS>.
  99 Note that  they must be properly  percent\-encoded.  This
 100 proxy  is used  when the  backend connection  is HTTP/2.
 101 First,  make  a CONNECT  request  to  the proxy  and  it
 102 connects  to the  backend  on behalf  of nghttpx.   This
 103 forms  tunnel.   After  that, nghttpx  performs  SSL/TLS
 104 handshake with  the downstream through the  tunnel.  The
 105 timeouts when connecting and  making CONNECT request can
 106 be     specified    by     \fI\%\-\-backend\-read\-timeout\fP    and
 107 \fI\%\-\-backend\-write\-timeout\fP options.
 108 .UNINDENT
 109 .SS Performance
 110 .INDENT 0.0
 111 .TP
 112 .B \-n, \-\-workers=<N>
 113 Set the number of worker threads.
 114 .sp
 115 Default: \fB1\fP
 116 .UNINDENT
 117 .INDENT 0.0
 118 .TP
 119 .B \-\-read\-rate=<SIZE>
 120 Set maximum  average read  rate on  frontend connection.
 121 Setting 0 to this option means read rate is unlimited.
 122 .sp
 123 Default: \fB0\fP
 124 .UNINDENT
 125 .INDENT 0.0
 126 .TP
 127 .B \-\-read\-burst=<SIZE>
 128 Set  maximum read  burst  size  on frontend  connection.
 129 Setting  0  to this  option  means  read burst  size  is
 130 unlimited.
 131 .sp
 132 Default: \fB0\fP
 133 .UNINDENT
 134 .INDENT 0.0
 135 .TP
 136 .B \-\-write\-rate=<SIZE>
 137 Set maximum  average write rate on  frontend connection.
 138 Setting 0 to this option means write rate is unlimited.
 139 .sp
 140 Default: \fB0\fP
 141 .UNINDENT
 142 .INDENT 0.0
 143 .TP
 144 .B \-\-write\-burst=<SIZE>
 145 Set  maximum write  burst size  on frontend  connection.
 146 Setting  0 to  this  option means  write  burst size  is
 147 unlimited.
 148 .sp
 149 Default: \fB0\fP
 150 .UNINDENT
 151 .INDENT 0.0
 152 .TP
 153 .B \-\-worker\-read\-rate=<SIZE>
 154 Set maximum average read rate on frontend connection per
 155 worker.  Setting  0 to  this option  means read  rate is
 156 unlimited.  Not implemented yet.
 157 .sp
 158 Default: \fB0\fP
 159 .UNINDENT
 160 .INDENT 0.0
 161 .TP
 162 .B \-\-worker\-read\-burst=<SIZE>
 163 Set maximum  read burst size on  frontend connection per
 164 worker.  Setting 0 to this  option means read burst size
 165 is unlimited.  Not implemented yet.
 166 .sp
 167 Default: \fB0\fP
 168 .UNINDENT
 169 .INDENT 0.0
 170 .TP
 171 .B \-\-worker\-write\-rate=<SIZE>
 172 Set maximum  average write  rate on  frontend connection
 173 per worker.  Setting  0 to this option  means write rate
 174 is unlimited.  Not implemented yet.
 175 .sp
 176 Default: \fB0\fP
 177 .UNINDENT
 178 .INDENT 0.0
 179 .TP
 180 .B \-\-worker\-write\-burst=<SIZE>
 181 Set maximum write burst  size on frontend connection per
 182 worker.  Setting 0 to this option means write burst size
 183 is unlimited.  Not implemented yet.
 184 .sp
 185 Default: \fB0\fP
 186 .UNINDENT
 187 .INDENT 0.0
 188 .TP
 189 .B \-\-worker\-frontend\-connections=<N>
 190 Set maximum number  of simultaneous connections frontend
 191 accepts.  Setting 0 means unlimited.
 192 .sp
 193 Default: \fB0\fP
 194 .UNINDENT
 195 .INDENT 0.0
 196 .TP
 197 .B \-\-backend\-http2\-connections\-per\-worker=<N>
 198 Set  maximum number  of HTTP/2  connections per  worker.
 199 The  default  value is  0,  which  means the  number  of
 200 backend addresses specified by \fI\%\-b\fP option.
 201 .UNINDENT
 202 .INDENT 0.0
 203 .TP
 204 .B \-\-backend\-http1\-connections\-per\-host=<N>
 205 Set   maximum  number   of  backend   concurrent  HTTP/1
 206 connections per host.  This option is meaningful when \fI\%\-s\fP
 207 option is used.  To limit  the number of connections per
 208 frontend        for       default        mode,       use
 209 \fI\%\-\-backend\-http1\-connections\-per\-frontend\fP\&.
 210 .sp
 211 Default: \fB8\fP
 212 .UNINDENT
 213 .INDENT 0.0
 214 .TP
 215 .B \-\-backend\-http1\-connections\-per\-frontend=<N>
 216 Set   maximum  number   of  backend   concurrent  HTTP/1
 217 connections per frontend.  This  option is only used for
 218 default mode.   0 means unlimited.  To  limit the number
 219 of connections  per host for  HTTP/2 or SPDY  proxy mode
 220 (\-s option), use \fI\%\-\-backend\-http1\-connections\-per\-host\fP\&.
 221 .sp
 222 Default: \fB0\fP
 223 .UNINDENT
 224 .INDENT 0.0
 225 .TP
 226 .B \-\-rlimit\-nofile=<N>
 227 Set maximum number of open files (RLIMIT_NOFILE) to <N>.
 228 If 0 is given, nghttpx does not set the limit.
 229 .sp
 230 Default: \fB0\fP
 231 .UNINDENT
 232 .INDENT 0.0
 233 .TP
 234 .B \-\-backend\-request\-buffer=<SIZE>
 235 Set buffer size used to store backend request.
 236 .sp
 237 Default: \fB16K\fP
 238 .UNINDENT
 239 .INDENT 0.0
 240 .TP
 241 .B \-\-backend\-response\-buffer=<SIZE>
 242 Set buffer size used to store backend response.
 243 .sp
 244 Default: \fB16K\fP
 245 .UNINDENT
 246 .SS Timeout
 247 .INDENT 0.0
 248 .TP
 249 .B \-\-frontend\-http2\-read\-timeout=<DURATION>
 250 Specify  read  timeout  for  HTTP/2  and  SPDY  frontend
 251 connection.
 252 .sp
 253 Default: \fB3m\fP
 254 .UNINDENT
 255 .INDENT 0.0
 256 .TP
 257 .B \-\-frontend\-read\-timeout=<DURATION>
 258 Specify read timeout for HTTP/1.1 frontend connection.
 259 .sp
 260 Default: \fB3m\fP
 261 .UNINDENT
 262 .INDENT 0.0
 263 .TP
 264 .B \-\-frontend\-write\-timeout=<DURATION>
 265 Specify write timeout for all frontend connections.
 266 .sp
 267 Default: \fB30s\fP
 268 .UNINDENT
 269 .INDENT 0.0
 270 .TP
 271 .B \-\-stream\-read\-timeout=<DURATION>
 272 Specify  read timeout  for HTTP/2  and SPDY  streams.  0
 273 means no timeout.
 274 .sp
 275 Default: \fB0\fP
 276 .UNINDENT
 277 .INDENT 0.0
 278 .TP
 279 .B \-\-stream\-write\-timeout=<DURATION>
 280 Specify write  timeout for  HTTP/2 and SPDY  streams.  0
 281 means no timeout.
 282 .sp
 283 Default: \fB0\fP
 284 .UNINDENT
 285 .INDENT 0.0
 286 .TP
 287 .B \-\-backend\-read\-timeout=<DURATION>
 288 Specify read timeout for backend connection.
 289 .sp
 290 Default: \fB3m\fP
 291 .UNINDENT
 292 .INDENT 0.0
 293 .TP
 294 .B \-\-backend\-write\-timeout=<DURATION>
 295 Specify write timeout for backend connection.
 296 .sp
 297 Default: \fB30s\fP
 298 .UNINDENT
 299 .INDENT 0.0
 300 .TP
 301 .B \-\-backend\-keep\-alive\-timeout=<DURATION>
 302 Specify keep\-alive timeout for backend connection.
 303 .sp
 304 Default: \fB2s\fP
 305 .UNINDENT
 306 .INDENT 0.0
 307 .TP
 308 .B \-\-listener\-disable\-timeout=<DURATION>
 309 After accepting  connection failed,  connection listener
 310 is disabled  for a given  amount of time.   Specifying 0
 311 disables this feature.
 312 .sp
 313 Default: \fB0\fP
 314 .UNINDENT
 315 .SS SSL/TLS
 316 .INDENT 0.0
 317 .TP
 318 .B \-\-ciphers=<SUITE>
 319 Set allowed  cipher list.  The  format of the  string is
 320 described in OpenSSL ciphers(1).
 321 .UNINDENT
 322 .INDENT 0.0
 323 .TP
 324 .B \-k, \-\-insecure
 325 Don\(aqt  verify   backend  server\(aqs  certificate   if  \fI\%\-p\fP,
 326 \fI\%\-\-client\fP    or    \fI\%\-\-http2\-bridge\fP     are    given    and
 327 \fI\%\-\-backend\-no\-tls\fP is not given.
 328 .UNINDENT
 329 .INDENT 0.0
 330 .TP
 331 .B \-\-cacert=<PATH>
 332 Set path to trusted CA  certificate file if \fI\%\-p\fP, \fI\%\-\-client\fP
 333 or \fI\%\-\-http2\-bridge\fP are given  and \fI\%\-\-backend\-no\-tls\fP is not
 334 given.  The file must be  in PEM format.  It can contain
 335 multiple  certificates.    If  the  linked   OpenSSL  is
 336 configured to  load system  wide certificates,  they are
 337 loaded at startup regardless of this option.
 338 .UNINDENT
 339 .INDENT 0.0
 340 .TP
 341 .B \-\-private\-key\-passwd\-file=<PATH>
 342 Path  to file  that contains  password for  the server\(aqs
 343 private key.   If none is  given and the private  key is
 344 password protected it\(aqll be requested interactively.
 345 .UNINDENT
 346 .INDENT 0.0
 347 .TP
 348 .B \-\-subcert=<KEYPATH>:<CERTPATH>
 349 Specify  additional certificate  and  private key  file.
 350 nghttpx will  choose certificates based on  the hostname
 351 indicated  by  client  using TLS  SNI  extension.   This
 352 option  can  be  used  multiple  times.   To  make  OCSP
 353 stapling work, <CERTPATH> must be absolute path.
 354 .UNINDENT
 355 .INDENT 0.0
 356 .TP
 357 .B \-\-backend\-tls\-sni\-field=<HOST>
 358 Explicitly  set the  content of  the TLS  SNI extension.
 359 This will default to the backend HOST name.
 360 .UNINDENT
 361 .INDENT 0.0
 362 .TP
 363 .B \-\-dh\-param\-file=<PATH>
 364 Path to file that contains  DH parameters in PEM format.
 365 Without  this   option,  DHE   cipher  suites   are  not
 366 available.
 367 .UNINDENT
 368 .INDENT 0.0
 369 .TP
 370 .B \-\-npn\-list=<LIST>
 371 Comma delimited list of  ALPN protocol identifier sorted
 372 in the  order of preference.  That  means most desirable
 373 protocol comes  first.  This  is used  in both  ALPN and
 374 NPN.  The parameter must be  delimited by a single comma
 375 only  and any  white spaces  are  treated as  a part  of
 376 protocol string.
 377 .sp
 378 Default: \fBh2,h2\-16,h2\-14,spdy/3.1,http/1.1\fP
 379 .UNINDENT
 380 .INDENT 0.0
 381 .TP
 382 .B \-\-verify\-client
 383 Require and verify client certificate.
 384 .UNINDENT
 385 .INDENT 0.0
 386 .TP
 387 .B \-\-verify\-client\-cacert=<PATH>
 388 Path  to file  that contains  CA certificates  to verify
 389 client certificate.  The file must be in PEM format.  It
 390 can contain multiple certificates.
 391 .UNINDENT
 392 .INDENT 0.0
 393 .TP
 394 .B \-\-client\-private\-key\-file=<PATH>
 395 Path to  file that contains  client private key  used in
 396 backend client authentication.
 397 .UNINDENT
 398 .INDENT 0.0
 399 .TP
 400 .B \-\-client\-cert\-file=<PATH>
 401 Path to  file that  contains client certificate  used in
 402 backend client authentication.
 403 .UNINDENT
 404 .INDENT 0.0
 405 .TP
 406 .B \-\-tls\-proto\-list=<LIST>
 407 Comma delimited list of  SSL/TLS protocol to be enabled.
 408 The following protocols  are available: TLSv1.2, TLSv1.1
 409 and   TLSv1.0.    The   name   matching   is   done   in
 410 case\-insensitive   manner.    The  parameter   must   be
 411 delimited by  a single comma  only and any  white spaces
 412 are treated as a part of protocol string.
 413 .sp
 414 Default: \fBTLSv1.2,TLSv1.1\fP
 415 .UNINDENT
 416 .INDENT 0.0
 417 .TP
 418 .B \-\-tls\-ticket\-key\-file=<PATH>
 419 Path  to file  that  contains 48  bytes  random data  to
 420 construct TLS  session ticket parameters.   This options
 421 can  be  used  repeatedly  to  specify  multiple  ticket
 422 parameters.  If several files  are given, only the first
 423 key is used to encrypt  TLS session tickets.  Other keys
 424 are accepted  but server  will issue new  session ticket
 425 with  first  key.   This allows  session  key  rotation.
 426 Please   note  that   key   rotation   does  not   occur
 427 automatically.   User should  rearrange files  or change
 428 options  values  and  restart  nghttpx  gracefully.   If
 429 opening or reading given file fails, all loaded keys are
 430 discarded and it is treated as if none of this option is
 431 given.  If this option is not given or an error occurred
 432 while  opening  or  reading  a file,  key  is  generated
 433 automatically and  renewed every 12hrs.  At  most 2 keys
 434 are stored in memory.
 435 .UNINDENT
 436 .INDENT 0.0
 437 .TP
 438 .B \-\-fetch\-ocsp\-response\-file=<PATH>
 439 Path to  fetch\-ocsp\-response script file.  It  should be
 440 absolute path.
 441 .sp
 442 Default: \fB/usr/local/share/nghttp2/fetch\-ocsp\-response\fP
 443 .UNINDENT
 444 .INDENT 0.0
 445 .TP
 446 .B \-\-ocsp\-update\-interval=<DURATION>
 447 Set interval to update OCSP response cache.
 448 .sp
 449 Default: \fB4h\fP
 450 .UNINDENT
 451 .INDENT 0.0
 452 .TP
 453 .B \-\-no\-ocsp
 454 Disable OCSP stapling.
 455 .UNINDENT
 456 .SS HTTP/2 and SPDY
 457 .INDENT 0.0
 458 .TP
 459 .B \-c, \-\-http2\-max\-concurrent\-streams=<N>
 460 Set the maximum number of  the concurrent streams in one
 461 HTTP/2 and SPDY session.
 462 .sp
 463 Default: \fB100\fP
 464 .UNINDENT
 465 .INDENT 0.0
 466 .TP
 467 .B \-\-frontend\-http2\-window\-bits=<N>
 468 Sets the  per\-stream initial window size  of HTTP/2 SPDY
 469 frontend connection.  For HTTP/2,  the size is 2**<N>\-1.
 470 For SPDY, the size is 2**<N>.
 471 .sp
 472 Default: \fB16\fP
 473 .UNINDENT
 474 .INDENT 0.0
 475 .TP
 476 .B \-\-frontend\-http2\-connection\-window\-bits=<N>
 477 Sets the  per\-connection window size of  HTTP/2 and SPDY
 478 frontend   connection.    For   HTTP/2,  the   size   is
 479 2**<N>\-1. For SPDY, the size is 2**<N>.
 480 .sp
 481 Default: \fB16\fP
 482 .UNINDENT
 483 .INDENT 0.0
 484 .TP
 485 .B \-\-frontend\-no\-tls
 486 Disable SSL/TLS on frontend connections.
 487 .UNINDENT
 488 .INDENT 0.0
 489 .TP
 490 .B \-\-backend\-http2\-window\-bits=<N>
 491 Sets  the   initial  window   size  of   HTTP/2  backend
 492 connection to 2**<N>\-1.
 493 .sp
 494 Default: \fB16\fP
 495 .UNINDENT
 496 .INDENT 0.0
 497 .TP
 498 .B \-\-backend\-http2\-connection\-window\-bits=<N>
 499 Sets the  per\-connection window  size of  HTTP/2 backend
 500 connection to 2**<N>\-1.
 501 .sp
 502 Default: \fB16\fP
 503 .UNINDENT
 504 .INDENT 0.0
 505 .TP
 506 .B \-\-backend\-no\-tls
 507 Disable SSL/TLS on backend connections.
 508 .UNINDENT
 509 .INDENT 0.0
 510 .TP
 511 .B \-\-http2\-no\-cookie\-crumbling
 512 Don\(aqt crumble cookie header field.
 513 .UNINDENT
 514 .INDENT 0.0
 515 .TP
 516 .B \-\-padding=<N>
 517 Add  at most  <N> bytes  to  a HTTP/2  frame payload  as
 518 padding.  Specify 0 to  disable padding.  This option is
 519 meant for debugging purpose  and not intended to enhance
 520 protocol security.
 521 .UNINDENT
 522 .INDENT 0.0
 523 .TP
 524 .B \-\-no\-server\-push
 525 Disable  HTTP/2  server  push.    Server  push  is  only
 526 supported  by default  mode and  HTTP/2 frontend.   SPDY
 527 frontend does not support server push.
 528 .UNINDENT
 529 .SS Mode
 530 .INDENT 0.0
 531 .TP
 532 .B (default mode)
 533 Accept  HTTP/2,  SPDY  and HTTP/1.1  over  SSL/TLS.   If
 534 \fI\%\-\-frontend\-no\-tls\fP is  used, accept HTTP/2  and HTTP/1.1.
 535 The  incoming HTTP/1.1  connection  can  be upgraded  to
 536 HTTP/2  through  HTTP  Upgrade.   The  protocol  to  the
 537 backend is HTTP/1.1.
 538 .UNINDENT
 539 .INDENT 0.0
 540 .TP
 541 .B \-s, \-\-http2\-proxy
 542 Like default mode, but enable secure proxy mode.
 543 .UNINDENT
 544 .INDENT 0.0
 545 .TP
 546 .B \-\-http2\-bridge
 547 Like default  mode, but communicate with  the backend in
 548 HTTP/2 over SSL/TLS.  Thus  the incoming all connections
 549 are converted  to HTTP/2  connection and relayed  to the
 550 backend.  See \fI\%\-\-backend\-http\-proxy\-uri\fP option if you are
 551 behind  the proxy  and want  to connect  to the  outside
 552 HTTP/2 proxy.
 553 .UNINDENT
 554 .INDENT 0.0
 555 .TP
 556 .B \-\-client
 557 Accept  HTTP/2   and  HTTP/1.1  without   SSL/TLS.   The
 558 incoming HTTP/1.1  connection can be upgraded  to HTTP/2
 559 connection through  HTTP Upgrade.   The protocol  to the
 560 backend is HTTP/2.   To use nghttpx as  a forward proxy,
 561 use \fI\%\-p\fP option instead.
 562 .UNINDENT
 563 .INDENT 0.0
 564 .TP
 565 .B \-p, \-\-client\-proxy
 566 Like \fI\%\-\-client\fP  option, but it also  requires the request
 567 path from frontend must be an absolute URI, suitable for
 568 use as a forward proxy.
 569 .UNINDENT
 570 .SS Logging
 571 .INDENT 0.0
 572 .TP
 573 .B \-L, \-\-log\-level=<LEVEL>
 574 Set the severity  level of log output.   <LEVEL> must be
 575 one of INFO, NOTICE, WARN, ERROR and FATAL.
 576 .sp
 577 Default: \fBNOTICE\fP
 578 .UNINDENT
 579 .INDENT 0.0
 580 .TP
 581 .B \-\-accesslog\-file=<PATH>
 582 Set path to write access log.  To reopen file, send USR1
 583 signal to nghttpx.
 584 .UNINDENT
 585 .INDENT 0.0
 586 .TP
 587 .B \-\-accesslog\-syslog
 588 Send  access log  to syslog.   If this  option is  used,
 589 \fI\%\-\-accesslog\-file\fP option is ignored.
 590 .UNINDENT
 591 .INDENT 0.0
 592 .TP
 593 .B \-\-accesslog\-format=<FORMAT>
 594 Specify  format  string  for access  log.   The  default
 595 format is combined format.   The following variables are
 596 available:
 597 .INDENT 7.0
 598 .IP \(bu 2
 599 $remote_addr: client IP address.
 600 .IP \(bu 2
 601 $time_local: local time in Common Log format.
 602 .IP \(bu 2
 603 $time_iso8601: local time in ISO 8601 format.
 604 .IP \(bu 2
 605 $request: HTTP request line.
 606 .IP \(bu 2
 607 $status: HTTP response status code.
 608 .IP \(bu 2
 609 $body_bytes_sent: the  number of bytes sent  to client
 610 as response body.
 611 .IP \(bu 2
 612 $http_<VAR>: value of HTTP  request header <VAR> where
 613 \(aq_\(aq in <VAR> is replaced with \(aq\-\(aq.
 614 .IP \(bu 2
 615 $remote_port: client  port.
 616 .IP \(bu 2
 617 $server_port: server port.
 618 .IP \(bu 2
 619 $request_time: request processing time in seconds with
 620 milliseconds resolution.
 621 .IP \(bu 2
 622 $pid: PID of the running process.
 623 .IP \(bu 2
 624 $alpn: ALPN identifier of the protocol which generates
 625 the response.   For HTTP/1,  ALPN is  always http/1.1,
 626 regardless of minor version.
 627 .UNINDENT
 628 .sp
 629 Default: \fB$remote_addr \- \- [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"\fP
 630 .UNINDENT
 631 .INDENT 0.0
 632 .TP
 633 .B \-\-errorlog\-file=<PATH>
 634 Set path to write error  log.  To reopen file, send USR1
 635 signal  to nghttpx.   stderr will  be redirected  to the
 636 error log file unless \fI\%\-\-errorlog\-syslog\fP is used.
 637 .sp
 638 Default: \fB/dev/stderr\fP
 639 .UNINDENT
 640 .INDENT 0.0
 641 .TP
 642 .B \-\-errorlog\-syslog
 643 Send  error log  to  syslog.  If  this  option is  used,
 644 \fI\%\-\-errorlog\-file\fP option is ignored.
 645 .UNINDENT
 646 .INDENT 0.0
 647 .TP
 648 .B \-\-syslog\-facility=<FACILITY>
 649 Set syslog facility to <FACILITY>.
 650 .sp
 651 Default: \fBdaemon\fP
 652 .UNINDENT
 653 .SS HTTP
 654 .INDENT 0.0
 655 .TP
 656 .B \-\-add\-x\-forwarded\-for
 657 Append  X\-Forwarded\-For header  field to  the downstream
 658 request.
 659 .UNINDENT
 660 .INDENT 0.0
 661 .TP
 662 .B \-\-strip\-incoming\-x\-forwarded\-for
 663 Strip X\-Forwarded\-For  header field from  inbound client
 664 requests.
 665 .UNINDENT
 666 .INDENT 0.0
 667 .TP
 668 .B \-\-no\-via
 669 Don\(aqt append to  Via header field.  If  Via header field
 670 is received, it is left unaltered.
 671 .UNINDENT
 672 .INDENT 0.0
 673 .TP
 674 .B \-\-no\-location\-rewrite
 675 Don\(aqt rewrite  location header field  on \fI\%\-\-http2\-bridge\fP,
 676 \fI\%\-\-client\fP  and  default   mode.   For  \fI\%\-\-http2\-proxy\fP  and
 677 \fI\%\-\-client\-proxy\fP mode,  location header field will  not be
 678 altered regardless of this option.
 679 .UNINDENT
 680 .INDENT 0.0
 681 .TP
 682 .B \-\-no\-host\-rewrite
 683 Don\(aqt  rewrite  host  and :authority  header  fields  on
 684 \fI\%\-\-http2\-bridge\fP,   \fI\%\-\-client\fP   and  default   mode.    For
 685 \fI\%\-\-http2\-proxy\fP  and  \fI\%\-\-client\-proxy\fP mode,  these  headers
 686 will not be altered regardless of this option.
 687 .UNINDENT
 688 .INDENT 0.0
 689 .TP
 690 .B \-\-altsvc=<PROTOID,PORT[,HOST,[ORIGIN]]>
 691 Specify   protocol  ID,   port,  host   and  origin   of
 692 alternative service.  <HOST>  and <ORIGIN> are optional.
 693 They  are advertised  in  alt\-svc header  field only  in
 694 HTTP/1.1  frontend.  This  option can  be used  multiple
 695 times   to   specify  multiple   alternative   services.
 696 Example: \fI\%\-\-altsvc\fP=h2,443
 697 .UNINDENT
 698 .INDENT 0.0
 699 .TP
 700 .B \-\-add\-response\-header=<HEADER>
 701 Specify  additional  header  field to  add  to  response
 702 header set.   This option just appends  header field and
 703 won\(aqt replace anything already  set.  This option can be
 704 used several  times to  specify multiple  header fields.
 705 Example: \fI\%\-\-add\-response\-header\fP="foo: bar"
 706 .UNINDENT
 707 .INDENT 0.0
 708 .TP
 709 .B \-\-header\-field\-buffer=<SIZE>
 710 Set maximum  buffer size for incoming  HTTP header field
 711 list.   This is  the sum  of  header name  and value  in
 712 bytes.
 713 .sp
 714 Default: \fB64K\fP
 715 .UNINDENT
 716 .INDENT 0.0
 717 .TP
 718 .B \-\-max\-header\-fields=<N>
 719 Set maximum number of incoming HTTP header fields, which
 720 appear in one request or response header field list.
 721 .sp
 722 Default: \fB100\fP
 723 .UNINDENT
 724 .SS Debug
 725 .INDENT 0.0
 726 .TP
 727 .B \-\-frontend\-http2\-dump\-request\-header=<PATH>
 728 Dumps request headers received by HTTP/2 frontend to the
 729 file denoted  in <PATH>.  The  output is done  in HTTP/1
 730 header field format and each header block is followed by
 731 an empty line.  This option  is not thread safe and MUST
 732 NOT be used with option \fI\%\-n\fP<N>, where <N> >= 2.
 733 .UNINDENT
 734 .INDENT 0.0
 735 .TP
 736 .B \-\-frontend\-http2\-dump\-response\-header=<PATH>
 737 Dumps response headers sent  from HTTP/2 frontend to the
 738 file denoted  in <PATH>.  The  output is done  in HTTP/1
 739 header field format and each header block is followed by
 740 an empty line.  This option  is not thread safe and MUST
 741 NOT be used with option \fI\%\-n\fP<N>, where <N> >= 2.
 742 .UNINDENT
 743 .INDENT 0.0
 744 .TP
 745 .B \-o, \-\-frontend\-frame\-debug
 746 Print HTTP/2 frames in  frontend to stderr.  This option
 747 is  not thread  safe and  MUST NOT  be used  with option
 748 \fI\%\-n\fP=N, where N >= 2.
 749 .UNINDENT
 750 .SS Process
 751 .INDENT 0.0
 752 .TP
 753 .B \-D, \-\-daemon
 754 Run in a background.  If \fI\%\-D\fP is used, the current working
 755 directory is changed to \(aq\fI/\fP\(aq.
 756 .UNINDENT
 757 .INDENT 0.0
 758 .TP
 759 .B \-\-pid\-file=<PATH>
 760 Set path to save PID of this program.
 761 .UNINDENT
 762 .INDENT 0.0
 763 .TP
 764 .B \-\-user=<USER>
 765 Run this program as <USER>.   This option is intended to
 766 be used to drop root privileges.
 767 .UNINDENT
 768 .SS Misc
 769 .INDENT 0.0
 770 .TP
 771 .B \-\-conf=<PATH>
 772 Load configuration from <PATH>.
 773 .sp
 774 Default: \fB/etc/nghttpx/nghttpx.conf\fP
 775 .UNINDENT
 776 .INDENT 0.0
 777 .TP
 778 .B \-v, \-\-version
 779 Print version and exit.
 780 .UNINDENT
 781 .INDENT 0.0
 782 .TP
 783 .B \-h, \-\-help
 784 Print this help and exit.
 785 .UNINDENT
 786 .sp
 787 The <SIZE> argument is an integer and an optional unit (e.g., 10K is
 788 10 * 1024).  Units are K, M and G (powers of 1024).
 789 .sp
 790 The <DURATION> argument is an integer and an optional unit (e.g., 1s
 791 is 1 second and 500ms is 500 milliseconds).  Units are h, m, s or ms
 792 (hours, minutes, seconds and milliseconds, respectively).  If a unit
 793 is omitted, a second is used as unit.
 794 .SH FILES
 795 .INDENT 0.0
 796 .TP
 797 .B \fI/etc/nghttpx/nghttpx.conf\fP
 798 The default configuration file path nghttpx searches at startup.
 799 The configuration file path can be changed using \fI\%\-\-conf\fP
 800 option.
 801 .sp
 802 Those lines which are staring \fB#\fP are treated as comment.
 803 .sp
 804 The option name in the configuration file is the long command\-line
 805 option name with leading \fB\-\-\fP stripped (e.g., \fBfrontend\fP).  Put
 806 \fB=\fP between option name and value.  Don\(aqt put extra leading or
 807 trailing spaces.
 808 .sp
 809 The options which do not take argument in the command\-line \fItake\fP
 810 argument in the configuration file.  Specify \fByes\fP as an argument
 811 (e.g., \fBhttp2\-proxy=yes\fP).  If other string is given, it is
 812 ignored.
 813 .sp
 814 To specify private key and certificate file which are given as
 815 positional arguments in command\-line, use \fBprivate\-key\-file\fP and
 816 \fBcertificate\-file\fP\&.
 817 .sp
 818 \fI\%\-\-conf\fP option cannot be used in the configuration file and
 819 will be ignored if specified.
 820 .UNINDENT
 821 .SH SIGNALS
 822 .INDENT 0.0
 823 .TP
 824 .B SIGQUIT
 825 Shutdown gracefully.  First accept pending connections and stop
 826 accepting connection.  After all connections are handled, nghttpx
 827 exits.
 828 .TP
 829 .B SIGUSR1
 830 Reopen log files.
 831 .TP
 832 .B SIGUSR2
 833 Fork and execute nghttpx.  It will execute the binary in the same
 834 path with same command\-line arguments and environment variables.
 835 After new process comes up, sending SIGQUIT to the original process
 836 to perform hot swapping.
 837 .UNINDENT
 838 .SH SERVER PUSH
 839 .sp
 840 nghttpx supports HTTP/2 server push in default mode.  nghttpx looks
 841 for Link header field (\fI\%RFC 5988\fP) in response headers from
 842 backend server and extracts URI\-reference with parameter
 843 \fBrel=preload\fP (see \fI\%preload\fP)
 844 and pushes those URIs to the frontend client. Here is a sample Link
 845 header field to initiate server push:
 846 .INDENT 0.0
 847 .INDENT 3.5
 848 .sp
 849 .nf
 850 .ft C
 851 Link: </fonts/font.woff>; rel=preload
 852 Link: </css/theme.css>; rel=preload
 853 .ft P
 854 .fi
 855 .UNINDENT
 856 .UNINDENT
 857 .sp
 858 Currently, the following restrictions are applied for server push:
 859 .INDENT 0.0
 860 .IP 1. 3
 861 URI\-reference must not contain authority.  If it exists, it is not
 862 pushed.  \fB/fonts/font.woff\fP and \fBcss/theme.css\fP are eligible to
 863 be pushed.  \fBhttps://example.org/fonts/font.woff\fP and
 864 \fB//example.org/css/theme.css\fP are not.
 865 .IP 2. 3
 866 The associated stream must have method "GET" or "POST".  The
 867 associated stream\(aqs status code must be 200.
 868 .UNINDENT
 869 .sp
 870 These limitations may be loosened in the future release.
 871 .SH UNIX DOMAIN SOCKET
 872 .sp
 873 nghttpx supports UNIX domain socket with a filename for both frontend
 874 and backend connections.
 875 .sp
 876 Please note that current nghttpx implementation does not delete a
 877 socket with a filename.  And on start up, if nghttpx detects that the
 878 specified socket already exists in the file system, nghttpx first
 879 deletes it.  However, if SIGUSR2 is used to execute new binary and
 880 both old and new configurations use same filename, new binary does not
 881 delete the socket and continues to use it.
 882 .SH OCSP STAPLING
 883 .sp
 884 OCSP query is done using external perl script \fBfetch\-ocsp\-response\fP,
 885 which has been developed as part of h2o project
 886 (\fI\%https://github.com/h2o/h2o\fP).
 887 .sp
 888 The script file is usually installed under
 889 \fB$(prefix)/share/nghttp2/\fP directory.  The actual path to script can
 890 be customized using \fI\%\-\-fetch\-ocsp\-response\-file\fP option.
 891 .SH SEE ALSO
 892 .sp
 893 \fInghttp(1)\fP, \fInghttpd(1)\fP, \fIh2load(1)\fP
 894 .SH AUTHOR
 895 Tatsuhiro Tsujikawa
 896 .SH COPYRIGHT
 897 2012, 2015, Tatsuhiro Tsujikawa
 898 .\" Generated by docutils manpage writer.
 899 .