summaryrefslogtreecommitdiffstats
path: root/doc/nghttpx.1.rst
blob: cee23f2a110fcd7c5a0a264fc0cad6d806abd75a (plain)
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
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
.. GENERATED by help2rst.py.  DO NOT EDIT DIRECTLY.

.. program:: nghttpx

nghttpx(1)
==========

SYNOPSIS
--------

**nghttpx** [OPTIONS]... [<PRIVATE_KEY> <CERT>]

DESCRIPTION
-----------

A reverse proxy for HTTP/3, HTTP/2, and HTTP/1.

.. describe:: <PRIVATE_KEY>

    
    Set  path  to  server's private  key.   Required  unless
    "no-tls" parameter is used in :option:`--frontend` option.

.. describe:: <CERT>

    Set  path  to  server's  certificate.   Required  unless
    "no-tls"  parameter is  used in  :option:`--frontend` option.   To
    make OCSP stapling work, this must be an absolute path.


OPTIONS
-------

The options are categorized into several groups.

Connections
~~~~~~~~~~~

.. option:: -b, --backend=(<HOST>,<PORT>|unix:<PATH>)[;[<PATTERN>[:...]][[;<PARAM>]...]


    Set  backend  host  and   port.   The  multiple  backend
    addresses are  accepted by repeating this  option.  UNIX
    domain socket  can be  specified by prefixing  path name
    with "unix:" (e.g., unix:/var/run/backend.sock).

    Optionally, if <PATTERN>s are given, the backend address
    is  only  used  if  request matches  the  pattern.   The
    pattern  matching is  closely  designed  to ServeMux  in
    net/http package of  Go programming language.  <PATTERN>
    consists of  path, host +  path or just host.   The path
    must start  with "*/*".  If  it ends with "*/*",  it matches
    all  request path  in  its subtree.   To  deal with  the
    request  to the  directory without  trailing slash,  the
    path which ends  with "*/*" also matches  the request path
    which  only  lacks  trailing  '*/*'  (e.g.,  path  "*/foo/*"
    matches request path  "*/foo*").  If it does  not end with
    "*/*", it  performs exact match against  the request path.
    If  host  is given,  it  performs  a match  against  the
    request host.   For a  request received on  the frontend
    listener with  "sni-fwd" parameter enabled, SNI  host is
    used instead of a request host.  If host alone is given,
    "*/*" is  appended to it,  so that it matches  all request
    paths  under the  host  (e.g., specifying  "nghttp2.org"
    equals  to "nghttp2.org/").   CONNECT method  is treated
    specially.  It  does not have  path, and we  don't allow
    empty path.  To workaround  this, we assume that CONNECT
    method has "*/*" as path.

    Patterns with  host take  precedence over  patterns with
    just path.   Then, longer patterns take  precedence over
    shorter ones.

    Host  can  include "\*"  in  the  left most  position  to
    indicate  wildcard match  (only suffix  match is  done).
    The "\*" must match at least one character.  For example,
    host    pattern    "\*.nghttp2.org"    matches    against
    "www.nghttp2.org"  and  "git.ngttp2.org", but  does  not
    match  against  "nghttp2.org".   The exact  hosts  match
    takes precedence over the wildcard hosts match.

    If path  part ends with  "\*", it is treated  as wildcard
    path.  The  wildcard path  behaves differently  from the
    normal path.  For normal path,  match is made around the
    boundary of path component  separator,"*/*".  On the other
    hand, the wildcard  path does not take  into account the
    path component  separator.  All paths which  include the
    wildcard  path  without  last  "\*" as  prefix,  and  are
    strictly longer than wildcard  path without last "\*" are
    matched.  "\*"  must match  at least one  character.  For
    example,  the   pattern  "*/foo\**"  matches   "*/foo/*"  and
    "*/foobar*".  But it does not match "*/foo*", or "*/fo*".

    If <PATTERN> is omitted or  empty string, "*/*" is used as
    pattern,  which  matches  all request  paths  (catch-all
    pattern).  The catch-all backend must be given.

    When doing  a match, nghttpx made  some normalization to
    pattern, request host and path.  For host part, they are
    converted to lower case.  For path part, percent-encoded
    unreserved characters  defined in RFC 3986  are decoded,
    and any  dot-segments (".."  and ".")   are resolved and
    removed.

    For   example,   :option:`-b`\'127.0.0.1,8080;nghttp2.org/httpbin/'
    matches the  request host "nghttp2.org" and  the request
    path "*/httpbin/get*", but does not match the request host
    "nghttp2.org" and the request path "*/index.html*".

    The  multiple <PATTERN>s  can  be specified,  delimiting
    them            by           ":".             Specifying
    :option:`-b`\'127.0.0.1,8080;nghttp2.org:www.nghttp2.org'  has  the
    same  effect  to specify  :option:`-b`\'127.0.0.1,8080;nghttp2.org'
    and :option:`-b`\'127.0.0.1,8080;www.nghttp2.org'.

    The backend addresses sharing same <PATTERN> are grouped
    together forming  load balancing  group.

    Several parameters <PARAM> are accepted after <PATTERN>.
    The  parameters are  delimited  by  ";".  The  available
    parameters       are:      "proto=<PROTO>",       "tls",
    "sni=<SNI_HOST>",         "fall=<N>",        "rise=<N>",
    "affinity=<METHOD>",    "dns",    "redirect-if-not-tls",
    "upgrade-scheme",                        "mruby=<PATH>",
    "read-timeout=<DURATION>",   "write-timeout=<DURATION>",
    "group=<GROUP>",  "group-weight=<N>", "weight=<N>",  and
    "dnf".    The  parameter   consists   of  keyword,   and
    optionally followed by "="  and value.  For example, the
    parameter "proto=h2" consists of the keyword "proto" and
    value "h2".  The parameter "tls" consists of the keyword
    "tls"  without value.   Each parameter  is described  as
    follows.

    The backend application protocol  can be specified using
    optional  "proto"   parameter,  and   in  the   form  of
    "proto=<PROTO>".  <PROTO> should be one of the following
    list  without  quotes:  "h2", "http/1.1".   The  default
    value of <PROTO> is  "http/1.1".  Note that usually "h2"
    refers to HTTP/2  over TLS.  But in this  option, it may
    mean HTTP/2  over cleartext TCP unless  "tls" keyword is
    used (see below).

    TLS  can   be  enabled  by  specifying   optional  "tls"
    parameter.  TLS is not enabled by default.

    With "sni=<SNI_HOST>" parameter, it can override the TLS
    SNI  field  value  with  given  <SNI_HOST>.   This  will
    default to the backend <HOST> name

    The  feature  to detect  whether  backend  is online  or
    offline can be enabled  using optional "fall" and "rise"
    parameters.   Using  "fall=<N>"  parameter,  if  nghttpx
    cannot connect  to a  this backend <N>  times in  a row,
    this  backend  is  assumed  to be  offline,  and  it  is
    excluded from load balancing.  If <N> is 0, this backend
    never  be excluded  from load  balancing whatever  times
    nghttpx cannot connect  to it, and this  is the default.
    There is  also "rise=<N>" parameter.  After  backend was
    excluded from load balancing group, nghttpx periodically
    attempts to make a connection to the failed backend, and
    if the  connection is made  successfully <N> times  in a
    row, the backend is assumed to  be online, and it is now
    eligible  for load  balancing target.   If <N>  is 0,  a
    backend  is permanently  offline, once  it goes  in that
    state, and this is the default behaviour.

    The     session     affinity    is     enabled     using
    "affinity=<METHOD>"  parameter.   If  "ip" is  given  in
    <METHOD>, client  IP based session affinity  is enabled.
    If "cookie"  is given in <METHOD>,  cookie based session
    affinity is  enabled.  If  "none" is given  in <METHOD>,
    session affinity  is disabled, and this  is the default.
    The session  affinity is  enabled per <PATTERN>.   If at
    least  one backend  has  "affinity"  parameter, and  its
    <METHOD> is not "none",  session affinity is enabled for
    all backend  servers sharing the same  <PATTERN>.  It is
    advised  to  set  "affinity" parameter  to  all  backend
    explicitly if session affinity  is desired.  The session
    affinity  may   break  if   one  of  the   backend  gets
    unreachable,  or   backend  settings  are   reloaded  or
    replaced by API.

    If   "affinity=cookie"    is   used,    the   additional
    configuration                is                required.
    "affinity-cookie-name=<NAME>" must be  used to specify a
    name     of     cookie      to     use.      Optionally,
    "affinity-cookie-path=<PATH>" can  be used to  specify a
    path   which   cookie    is   applied.    The   optional
    "affinity-cookie-secure=<SECURE>"  controls  the  Secure
    attribute of a cookie.  The default value is "auto", and
    the Secure attribute is  determined by a request scheme.
    If a request scheme is "https", then Secure attribute is
    set.  Otherwise, it  is not set.  If  <SECURE> is "yes",
    the  Secure attribute  is  always set.   If <SECURE>  is
    "no",   the   Secure   attribute  is   always   omitted.
    "affinity-cookie-stickiness=<STICKINESS>"       controls
    stickiness  of   this  affinity.   If   <STICKINESS>  is
    "loose", removing or adding a backend server might break
    the affinity  and the  request might  be forwarded  to a
    different backend server.   If <STICKINESS> is "strict",
    removing the designated  backend server breaks affinity,
    but adding  new backend server does  not cause breakage.
    If  the designated  backend server  becomes unavailable,
    new backend server is chosen  as if the request does not
    have  an  affinity  cookie.   <STICKINESS>  defaults  to
    "loose".

    By default, name resolution of backend host name is done
    at  start  up,  or reloading  configuration.   If  "dns"
    parameter   is  given,   name  resolution   takes  place
    dynamically.  This is useful  if backend address changes
    frequently.   If  "dns"  is given,  name  resolution  of
    backend   host   name   at  start   up,   or   reloading
    configuration is skipped.

    If "redirect-if-not-tls" parameter  is used, the matched
    backend  requires   that  frontend  connection   is  TLS
    encrypted.  If it isn't, nghttpx responds to the request
    with 308  status code, and  https URI the  client should
    use instead  is included in Location  header field.  The
    port number in  redirect URI is 443 by  default, and can
    be  changed using  :option:`--redirect-https-port` option.   If at
    least one  backend has  "redirect-if-not-tls" parameter,
    this feature is enabled  for all backend servers sharing
    the   same   <PATTERN>.    It    is   advised   to   set
    "redirect-if-no-tls"    parameter   to    all   backends
    explicitly if this feature is desired.

    If "upgrade-scheme"  parameter is used along  with "tls"
    parameter, HTTP/2 :scheme pseudo header field is changed
    to "https" from "http" when forwarding a request to this
    particular backend.  This is  a workaround for a backend
    server  which  requires  "https" :scheme  pseudo  header
    field on TLS encrypted connection.

    "mruby=<PATH>"  parameter  specifies  a  path  to  mruby
    script  file  which  is  invoked when  this  pattern  is
    matched.  All backends which share the same pattern must
    have the same mruby path.

    "read-timeout=<DURATION>" and "write-timeout=<DURATION>"
    parameters  specify the  read and  write timeout  of the
    backend connection  when this  pattern is  matched.  All
    backends which share the same pattern must have the same
    timeouts.  If these timeouts  are entirely omitted for a
    pattern,            :option:`--backend-read-timeout`           and
    :option:`--backend-write-timeout` are used.

    "group=<GROUP>"  parameter specifies  the name  of group
    this backend address belongs to.  By default, it belongs
    to  the unnamed  default group.   The name  of group  is
    unique   per   pattern.   "group-weight=<N>"   parameter
    specifies the  weight of  the group.  The  higher weight
    gets  more frequently  selected  by  the load  balancing
    algorithm.  <N> must be  [1, 256] inclusive.  The weight
    8 has 4 times more weight  than 2.  <N> must be the same
    for  all addresses  which  share the  same <GROUP>.   If
    "group-weight" is  omitted in an address,  but the other
    address  which  belongs  to  the  same  group  specifies
    "group-weight",   its    weight   is   used.     If   no
    "group-weight"  is  specified  for  all  addresses,  the
    weight of a group becomes 1.  "group" and "group-weight"
    are ignored if session affinity is enabled.

    "weight=<N>"  parameter  specifies  the  weight  of  the
    backend  address  inside  a  group  which  this  address
    belongs  to.  The  higher  weight  gets more  frequently
    selected by  the load balancing algorithm.   <N> must be
    [1,  256] inclusive.   The  weight 8  has  4 times  more
    weight  than weight  2.  If  this parameter  is omitted,
    weight  becomes  1.   "weight"  is  ignored  if  session
    affinity is enabled.

    If "dnf" parameter is  specified, an incoming request is
    not forwarded to a backend  and just consumed along with
    the  request body  (actually a  backend server  never be
    contacted).  It  is expected  that the HTTP  response is
    generated by mruby  script (see "mruby=<PATH>" parameter
    above).  "dnf" is an abbreviation of "do not forward".

    Since ";" and ":" are  used as delimiter, <PATTERN> must
    not contain  these characters.  In order  to include ":"
    in  <PATTERN>,  one  has  to  specify  "%3A"  (which  is
    percent-encoded  from of  ":") instead.   Since ";"  has
    special  meaning  in shell,  the  option  value must  be
    quoted.


    Default: ``127.0.0.1,80``

.. option:: -f, --frontend=(<HOST>,<PORT>|unix:<PATH>)[[;<PARAM>]...]

    Set  frontend  host and  port.   If  <HOST> is  '\*',  it
    assumes  all addresses  including  both  IPv4 and  IPv6.
    UNIX domain  socket can  be specified by  prefixing path
    name  with  "unix:" (e.g.,  unix:/var/run/nghttpx.sock).
    This  option can  be used  multiple times  to listen  to
    multiple addresses.

    This option  can take  0 or  more parameters,  which are
    described  below.   Note   that  "api"  and  "healthmon"
    parameters are mutually exclusive.

    Optionally, TLS  can be disabled by  specifying "no-tls"
    parameter.  TLS is enabled by default.

    If "sni-fwd" parameter is  used, when performing a match
    to select a backend server,  SNI host name received from
    the client  is used  instead of  the request  host.  See
    :option:`--backend` option about the pattern match.

    To  make this  frontend as  API endpoint,  specify "api"
    parameter.   This   is  disabled  by  default.    It  is
    important  to  limit the  access  to  the API  frontend.
    Otherwise, someone  may change  the backend  server, and
    break your services,  or expose confidential information
    to the outside the world.

    To  make  this  frontend  as  health  monitor  endpoint,
    specify  "healthmon"  parameter.   This is  disabled  by
    default.  Any  requests which come through  this address
    are replied with 200 HTTP status, without no body.

    To accept  PROXY protocol  version 1  and 2  on frontend
    connection,  specify  "proxyproto" parameter.   This  is
    disabled by default.

    To  receive   HTTP/3  (QUIC)  traffic,   specify  "quic"
    parameter.  It  makes nghttpx listen on  UDP port rather
    than  TCP   port.   UNIX   domain  socket,   "api",  and
    "healthmon"  parameters  cannot   be  used  with  "quic"
    parameter.


    Default: ``*,3000``

.. option:: --backlog=<N>

    Set listen backlog size.

    Default: ``65536``

.. option:: --backend-address-family=(auto|IPv4|IPv6)

    Specify  address  family  of  backend  connections.   If
    "auto" is given, both IPv4  and IPv6 are considered.  If
    "IPv4" is  given, only  IPv4 address is  considered.  If
    "IPv6" is given, only IPv6 address is considered.

    Default: ``auto``

.. option:: --backend-http-proxy-uri=<URI>

    Specify      proxy       URI      in       the      form
    http://[<USER>:<PASS>@]<PROXY>:<PORT>.    If   a   proxy
    requires  authentication,  specify  <USER>  and  <PASS>.
    Note that  they must be properly  percent-encoded.  This
    proxy  is used  when the  backend connection  is HTTP/2.
    First,  make  a CONNECT  request  to  the proxy  and  it
    connects  to the  backend  on behalf  of nghttpx.   This
    forms  tunnel.   After  that, nghttpx  performs  SSL/TLS
    handshake with  the downstream through the  tunnel.  The
    timeouts when connecting and  making CONNECT request can
    be     specified    by     :option:`--backend-read-timeout`    and
    :option:`--backend-write-timeout` options.


Performance
~~~~~~~~~~~

.. option:: -n, --workers=<N>

    Set the number of worker threads.

    Default: ``1``

.. option:: --single-thread

    Run everything in one  thread inside the worker process.
    This   feature   is   provided  for   better   debugging
    experience,  or  for  the platforms  which  lack  thread
    support.   If  threading  is disabled,  this  option  is
    always enabled.

.. option:: --read-rate=<SIZE>

    Set maximum  average read  rate on  frontend connection.
    Setting 0 to this option means read rate is unlimited.

    Default: ``0``

.. option:: --read-burst=<SIZE>

    Set  maximum read  burst  size  on frontend  connection.
    Setting  0  to this  option  means  read burst  size  is
    unlimited.

    Default: ``0``

.. option:: --write-rate=<SIZE>

    Set maximum  average write rate on  frontend connection.
    Setting 0 to this option means write rate is unlimited.

    Default: ``0``

.. option:: --write-burst=<SIZE>

    Set  maximum write  burst size  on frontend  connection.
    Setting  0 to  this  option means  write  burst size  is
    unlimited.

    Default: ``0``

.. option:: --worker-read-rate=<SIZE>

    Set maximum average read rate on frontend connection per
    worker.  Setting  0 to  this option  means read  rate is
    unlimited.  Not implemented yet.

    Default: ``0``

.. option:: --worker-read-burst=<SIZE>

    Set maximum  read burst size on  frontend connection per
    worker.  Setting 0 to this  option means read burst size
    is unlimited.  Not implemented yet.

    Default: ``0``

.. option:: --worker-write-rate=<SIZE>

    Set maximum  average write  rate on  frontend connection
    per worker.  Setting  0 to this option  means write rate
    is unlimited.  Not implemented yet.

    Default: ``0``

.. option:: --worker-write-burst=<SIZE>

    Set maximum write burst  size on frontend connection per
    worker.  Setting 0 to this option means write burst size
    is unlimited.  Not implemented yet.

    Default: ``0``

.. option:: --worker-frontend-connections=<N>

    Set maximum number  of simultaneous connections frontend
    accepts.  Setting 0 means unlimited.

    Default: ``0``

.. option:: --backend-connections-per-host=<N>

    Set  maximum number  of  backend concurrent  connections
    (and/or  streams in  case  of HTTP/2)  per origin  host.
    This option  is meaningful when :option:`--http2-proxy`  option is
    used.   The  origin  host  is  determined  by  authority
    portion of  request URI (or :authority  header field for
    HTTP/2).   To  limit  the   number  of  connections  per
    frontend        for       default        mode,       use
    :option:`--backend-connections-per-frontend`\.

    Default: ``8``

.. option:: --backend-connections-per-frontend=<N>

    Set  maximum number  of  backend concurrent  connections
    (and/or streams  in case of HTTP/2)  per frontend.  This
    option  is   only  used  for  default   mode.   0  means
    unlimited.  To limit the  number of connections per host
    with          :option:`--http2-proxy`         option,          use
    :option:`--backend-connections-per-host`\.

    Default: ``0``

.. option:: --rlimit-nofile=<N>

    Set maximum number of open files (RLIMIT_NOFILE) to <N>.
    If 0 is given, nghttpx does not set the limit.

    Default: ``0``

.. option:: --rlimit-memlock=<N>

    Set maximum number of bytes of memory that may be locked
    into  RAM.  If  0 is  given,  nghttpx does  not set  the
    limit.

    Default: ``0``

.. option:: --backend-request-buffer=<SIZE>

    Set buffer size used to store backend request.

    Default: ``16K``

.. option:: --backend-response-buffer=<SIZE>

    Set buffer size used to store backend response.

    Default: ``128K``

.. option:: --fastopen=<N>

    Enables  "TCP Fast  Open" for  the listening  socket and
    limits the  maximum length for the  queue of connections
    that have not yet completed the three-way handshake.  If
    value is 0 then fast open is disabled.

    Default: ``0``

.. option:: --no-kqueue

    Don't use  kqueue.  This  option is only  applicable for
    the platforms  which have kqueue.  For  other platforms,
    this option will be simply ignored.


Timeout
~~~~~~~

.. option:: --frontend-http2-idle-timeout=<DURATION>

    Specify idle timeout for HTTP/2 frontend connection.  If
    no active streams exist for this duration, connection is
    closed.

    Default: ``3m``

.. option:: --frontend-http3-idle-timeout=<DURATION>

    Specify idle timeout for HTTP/3 frontend connection.  If
    no active streams exist for this duration, connection is
    closed.

    Default: ``3m``

.. option:: --frontend-write-timeout=<DURATION>

    Specify write timeout for all frontend connections.

    Default: ``30s``

.. option:: --frontend-keep-alive-timeout=<DURATION>

    Specify   keep-alive   timeout   for   frontend   HTTP/1
    connection.

    Default: ``1m``

.. option:: --frontend-header-timeout=<DURATION>

    Specify  duration  that the  server  waits  for an  HTTP
    request  header fields  to be  received completely.   On
    timeout, HTTP/1 and HTTP/2  connections are closed.  For
    HTTP/3,  the  stream  is shutdown,  and  the  connection
    itself is left intact.

    Default: ``1m``

.. option:: --stream-read-timeout=<DURATION>

    Specify  read timeout  for HTTP/2  streams.  0  means no
    timeout.

    Default: ``0``

.. option:: --stream-write-timeout=<DURATION>

    Specify write  timeout for  HTTP/2 streams.  0  means no
    timeout.

    Default: ``1m``

.. option:: --backend-read-timeout=<DURATION>

    Specify read timeout for backend connection.

    Default: ``1m``

.. option:: --backend-write-timeout=<DURATION>

    Specify write timeout for backend connection.

    Default: ``30s``

.. option:: --backend-connect-timeout=<DURATION>

    Specify  timeout before  establishing TCP  connection to
    backend.

    Default: ``30s``

.. option:: --backend-keep-alive-timeout=<DURATION>

    Specify   keep-alive   timeout    for   backend   HTTP/1
    connection.

    Default: ``2s``

.. option:: --listener-disable-timeout=<DURATION>

    After accepting  connection failed,  connection listener
    is disabled  for a given  amount of time.   Specifying 0
    disables this feature.

    Default: ``30s``

.. option:: --frontend-http2-setting-timeout=<DURATION>

    Specify  timeout before  SETTINGS ACK  is received  from
    client.

    Default: ``10s``

.. option:: --backend-http2-settings-timeout=<DURATION>

    Specify  timeout before  SETTINGS ACK  is received  from
    backend server.

    Default: ``10s``

.. option:: --backend-max-backoff=<DURATION>

    Specify  maximum backoff  interval.  This  is used  when
    doing health  check against offline backend  (see "fail"
    parameter  in :option:`--backend`  option).   It is  also used  to
    limit  the  maximum   interval  to  temporarily  disable
    backend  when nghttpx  failed to  connect to  it.  These
    intervals are calculated  using exponential backoff, and
    consecutive failed attempts increase the interval.  This
    option caps its maximum value.

    Default: ``2m``


SSL/TLS
~~~~~~~

.. option:: --ciphers=<SUITE>

    Set allowed  cipher list  for frontend  connection.  The
    format of the string is described in OpenSSL ciphers(1).
    This option  sets cipher suites for  TLSv1.2 or earlier.
    Use :option:`--tls13-ciphers` for TLSv1.3.

    Default: ``ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384``

.. option:: --tls13-ciphers=<SUITE>

    Set allowed  cipher list  for frontend  connection.  The
    format of the string is described in OpenSSL ciphers(1).
    This  option  sets  cipher   suites  for  TLSv1.3.   Use
    :option:`--ciphers` for TLSv1.2 or earlier.

    Default: ``TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256``

.. option:: --client-ciphers=<SUITE>

    Set  allowed cipher  list for  backend connection.   The
    format of the string is described in OpenSSL ciphers(1).
    This option  sets cipher suites for  TLSv1.2 or earlier.
    Use :option:`--tls13-client-ciphers` for TLSv1.3.

    Default: ``ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384``

.. option:: --tls13-client-ciphers=<SUITE>

    Set  allowed cipher  list for  backend connection.   The
    format of the string is described in OpenSSL ciphers(1).
    This  option  sets  cipher   suites  for  TLSv1.3.   Use
    :option:`--tls13-client-ciphers` for TLSv1.2 or earlier.

    Default: ``TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256``

.. option:: --ecdh-curves=<LIST>

    Set  supported  curve  list  for  frontend  connections.
    <LIST> is a  colon separated list of curve  NID or names
    in the preference order.  The supported curves depend on
    the  linked  OpenSSL  library.  This  function  requires
    OpenSSL >= 1.0.2.

    Default: ``X25519:P-256:P-384:P-521``

.. option:: -k, --insecure

    Don't  verify backend  server's  certificate  if TLS  is
    enabled for backend connections.

.. option:: --cacert=<PATH>

    Set path to trusted CA  certificate file.  It is used in
    backend  TLS connections  to verify  peer's certificate.
    It is also used to  verify OCSP response from the script
    set by :option:`--fetch-ocsp-response-file`\.  The  file must be in
    PEM format.   It can contain multiple  certificates.  If
    the  linked OpenSSL  is configured  to load  system wide
    certificates, they  are loaded at startup  regardless of
    this option.

.. option:: --private-key-passwd-file=<PATH>

    Path  to file  that contains  password for  the server's
    private key.   If none is  given and the private  key is
    password protected it'll be requested interactively.

.. option:: --subcert=<KEYPATH>:<CERTPATH>[[;<PARAM>]...]

    Specify  additional certificate  and  private key  file.
    nghttpx will  choose certificates based on  the hostname
    indicated by client using TLS SNI extension.  If nghttpx
    is  built with  OpenSSL  >= 1.0.2,  the shared  elliptic
    curves (e.g., P-256) between  client and server are also
    taken into  consideration.  This allows nghttpx  to send
    ECDSA certificate  to modern clients, while  sending RSA
    based certificate to older  clients.  This option can be
    used  multiple  times.   To  make  OCSP  stapling  work,
    <CERTPATH> must be absolute path.

    Additional parameter  can be specified in  <PARAM>.  The
    available <PARAM> is "sct-dir=<DIR>".

    "sct-dir=<DIR>"  specifies the  path to  directory which
    contains        \*.sct        files        for        TLS
    signed_certificate_timestamp extension (RFC 6962).  This
    feature   requires   OpenSSL   >=   1.0.2.    See   also
    :option:`--tls-sct-dir` option.

.. option:: --dh-param-file=<PATH>

    Path to file that contains  DH parameters in PEM format.
    Without  this   option,  DHE   cipher  suites   are  not
    available.

.. option:: --alpn-list=<LIST>

    Comma delimited list of  ALPN protocol identifier sorted
    in the  order of preference.  That  means most desirable
    protocol comes  first.  The parameter must  be delimited
    by a single comma only  and any white spaces are treated
    as a part of protocol string.

    Default: ``h2,h2-16,h2-14,http/1.1``

.. option:: --verify-client

    Require and verify client certificate.

.. option:: --verify-client-cacert=<PATH>

    Path  to file  that contains  CA certificates  to verify
    client certificate.  The file must be in PEM format.  It
    can contain multiple certificates.

.. option:: --verify-client-tolerate-expired

    Accept  expired  client  certificate.   Operator  should
    handle  the expired  client  certificate  by some  means
    (e.g.,  mruby  script).   Otherwise, this  option  might
    cause a security risk.

.. option:: --client-private-key-file=<PATH>

    Path to  file that contains  client private key  used in
    backend client authentication.

.. option:: --client-cert-file=<PATH>

    Path to  file that  contains client certificate  used in
    backend client authentication.

.. option:: --tls-min-proto-version=<VER>

    Specify minimum SSL/TLS protocol.   The name matching is
    done in  case-insensitive manner.  The  versions between
    :option:`--tls-min-proto-version` and  :option:`\--tls-max-proto-version` are
    enabled.  If the protocol list advertised by client does
    not  overlap  this range,  you  will  receive the  error
    message "unknown protocol".  If a protocol version lower
    than TLSv1.2 is specified, make sure that the compatible
    ciphers are  included in :option:`--ciphers` option.   The default
    cipher  list  only   includes  ciphers  compatible  with
    TLSv1.2 or above.  The available versions are:
    TLSv1.3, TLSv1.2, TLSv1.1, and TLSv1.0

    Default: ``TLSv1.2``

.. option:: --tls-max-proto-version=<VER>

    Specify maximum SSL/TLS protocol.   The name matching is
    done in  case-insensitive manner.  The  versions between
    :option:`--tls-min-proto-version` and  :option:`\--tls-max-proto-version` are
    enabled.  If the protocol list advertised by client does
    not  overlap  this range,  you  will  receive the  error
    message "unknown protocol".  The available versions are:
    TLSv1.3, TLSv1.2, TLSv1.1, and TLSv1.0

    Default: ``TLSv1.3``

.. option:: --tls-ticket-key-file=<PATH>

    Path to file that contains  random data to construct TLS
    session ticket  parameters.  If aes-128-cbc is  given in
    :option:`--tls-ticket-key-cipher`\, the  file must  contain exactly
    48    bytes.     If     aes-256-cbc    is    given    in
    :option:`--tls-ticket-key-cipher`\, the  file must  contain exactly
    80  bytes.   This  options  can be  used  repeatedly  to
    specify  multiple ticket  parameters.  If  several files
    are given,  only the  first key is  used to  encrypt TLS
    session  tickets.  Other  keys are  accepted but  server
    will  issue new  session  ticket with  first key.   This
    allows  session  key  rotation.  Please  note  that  key
    rotation  does  not  occur automatically.   User  should
    rearrange  files or  change options  values and  restart
    nghttpx gracefully.   If opening  or reading  given file
    fails, all loaded  keys are discarded and  it is treated
    as if none  of this option is given.  If  this option is
    not given or an error  occurred while opening or reading
    a file,  key is  generated every  1 hour  internally and
    they are  valid for  12 hours.   This is  recommended if
    ticket  key sharing  between  nghttpx  instances is  not
    required.

.. option:: --tls-ticket-key-memcached=<HOST>,<PORT>[;tls]

    Specify address  of memcached  server to get  TLS ticket
    keys for  session resumption.   This enables  shared TLS
    ticket key between  multiple nghttpx instances.  nghttpx
    does not set TLS ticket  key to memcached.  The external
    ticket key generator is required.  nghttpx just gets TLS
    ticket  keys  from  memcached, and  use  them,  possibly
    replacing current set  of keys.  It is up  to extern TLS
    ticket  key generator  to rotate  keys frequently.   See
    "TLS SESSION  TICKET RESUMPTION" section in  manual page
    to know the data format in memcached entry.  Optionally,
    memcached  connection  can  be  encrypted  with  TLS  by
    specifying "tls" parameter.

.. option:: --tls-ticket-key-memcached-address-family=(auto|IPv4|IPv6)

    Specify address  family of memcached connections  to get
    TLS ticket keys.  If "auto" is given, both IPv4 and IPv6
    are considered.   If "IPv4" is given,  only IPv4 address
    is considered.  If "IPv6" is given, only IPv6 address is
    considered.

    Default: ``auto``

.. option:: --tls-ticket-key-memcached-interval=<DURATION>

    Set interval to get TLS ticket keys from memcached.

    Default: ``10m``

.. option:: --tls-ticket-key-memcached-max-retry=<N>

    Set  maximum   number  of  consecutive   retries  before
    abandoning TLS ticket key  retrieval.  If this number is
    reached,  the  attempt  is considered  as  failure,  and
    "failure" count  is incremented by 1,  which contributed
    to            the            value            controlled
    :option:`--tls-ticket-key-memcached-max-fail` option.

    Default: ``3``

.. option:: --tls-ticket-key-memcached-max-fail=<N>

    Set  maximum   number  of  consecutive   failure  before
    disabling TLS ticket until next scheduled key retrieval.

    Default: ``2``

.. option:: --tls-ticket-key-cipher=<CIPHER>

    Specify cipher  to encrypt TLS session  ticket.  Specify
    either   aes-128-cbc   or  aes-256-cbc.    By   default,
    aes-128-cbc is used.

.. option:: --tls-ticket-key-memcached-cert-file=<PATH>

    Path to client certificate  for memcached connections to
    get TLS ticket keys.

.. option:: --tls-ticket-key-memcached-private-key-file=<PATH>

    Path to client private  key for memcached connections to
    get TLS ticket keys.

.. option:: --fetch-ocsp-response-file=<PATH>

    Path to  fetch-ocsp-response script file.  It  should be
    absolute path.

    Default: ``/usr/local/share/nghttp2/fetch-ocsp-response``

.. option:: --ocsp-update-interval=<DURATION>

    Set interval to update OCSP response cache.

    Default: ``4h``

.. option:: --ocsp-startup

    Start  accepting connections  after initial  attempts to
    get OCSP responses  finish.  It does not  matter some of
    the  attempts  fail.  This  feature  is  useful if  OCSP
    responses   must    be   available    before   accepting
    connections.

.. option:: --no-verify-ocsp

    nghttpx does not verify OCSP response.

.. option:: --no-ocsp

    Disable OCSP stapling.

.. option:: --tls-session-cache-memcached=<HOST>,<PORT>[;tls]

    Specify  address of  memcached server  to store  session
    cache.   This  enables   shared  session  cache  between
    multiple   nghttpx  instances.    Optionally,  memcached
    connection can be encrypted with TLS by specifying "tls"
    parameter.

.. option:: --tls-session-cache-memcached-address-family=(auto|IPv4|IPv6)

    Specify address family of memcached connections to store
    session cache.  If  "auto" is given, both  IPv4 and IPv6
    are considered.   If "IPv4" is given,  only IPv4 address
    is considered.  If "IPv6" is given, only IPv6 address is
    considered.

    Default: ``auto``

.. option:: --tls-session-cache-memcached-cert-file=<PATH>

    Path to client certificate  for memcached connections to
    store session cache.

.. option:: --tls-session-cache-memcached-private-key-file=<PATH>

    Path to client private  key for memcached connections to
    store session cache.

.. option:: --tls-dyn-rec-warmup-threshold=<SIZE>

    Specify the  threshold size for TLS  dynamic record size
    behaviour.  During  a TLS  session, after  the threshold
    number of bytes  have been written, the  TLS record size
    will be increased to the maximum allowed (16K).  The max
    record size will  continue to be used on  the active TLS
    session.  After  :option:`--tls-dyn-rec-idle-timeout` has elapsed,
    the record size is reduced  to 1300 bytes.  Specify 0 to
    always use  the maximum record size,  regardless of idle
    period.   This  behaviour  applies   to  all  TLS  based
    frontends, and TLS HTTP/2 backends.

    Default: ``1M``

.. option:: --tls-dyn-rec-idle-timeout=<DURATION>

    Specify TLS dynamic record  size behaviour timeout.  See
    :option:`--tls-dyn-rec-warmup-threshold`  for   more  information.
    This behaviour  applies to all TLS  based frontends, and
    TLS HTTP/2 backends.

    Default: ``1s``

.. option:: --no-http2-cipher-block-list

    Allow  block  listed  cipher suite  on  frontend  HTTP/2
    connection.                                          See
    https://tools.ietf.org/html/rfc7540#appendix-A  for  the
    complete HTTP/2 cipher suites block list.

.. option:: --client-no-http2-cipher-block-list

    Allow  block  listed  cipher  suite  on  backend  HTTP/2
    connection.                                          See
    https://tools.ietf.org/html/rfc7540#appendix-A  for  the
    complete HTTP/2 cipher suites block list.

.. option:: --tls-sct-dir=<DIR>

    Specifies the  directory where  \*.sct files  exist.  All
    \*.sct   files   in  <DIR>   are   read,   and  sent   as
    extension_data of  TLS signed_certificate_timestamp (RFC
    6962)  to  client.   These   \*.sct  files  are  for  the
    certificate   specified   in   positional   command-line
    argument <CERT>, or  certificate option in configuration
    file.   For   additional  certificates,   use  :option:`--subcert`
    option.  This option requires OpenSSL >= 1.0.2.

.. option:: --psk-secrets=<PATH>

    Read list of PSK identity and secrets from <PATH>.  This
    is used for frontend connection.  The each line of input
    file  is  formatted  as  <identity>:<hex-secret>,  where
    <identity> is  PSK identity, and <hex-secret>  is secret
    in hex.  An  empty line, and line which  starts with '#'
    are skipped.  The default  enabled cipher list might not
    contain any PSK cipher suite.  In that case, desired PSK
    cipher suites  must be  enabled using  :option:`--ciphers` option.
    The  desired PSK  cipher suite  may be  block listed  by
    HTTP/2.   To  use  those   cipher  suites  with  HTTP/2,
    consider  to  use  :option:`--no-http2-cipher-block-list`  option.
    But be aware its implications.

.. option:: --client-psk-secrets=<PATH>

    Read PSK identity and secrets from <PATH>.  This is used
    for backend connection.  The each  line of input file is
    formatted  as <identity>:<hex-secret>,  where <identity>
    is PSK identity, and <hex-secret>  is secret in hex.  An
    empty line, and line which  starts with '#' are skipped.
    The first identity and  secret pair encountered is used.
    The default  enabled cipher  list might not  contain any
    PSK  cipher suite.   In  that case,  desired PSK  cipher
    suites  must be  enabled using  :option:`--client-ciphers` option.
    The  desired PSK  cipher suite  may be  block listed  by
    HTTP/2.   To  use  those   cipher  suites  with  HTTP/2,
    consider   to  use   :option:`--client-no-http2-cipher-block-list`
    option.  But be aware its implications.

.. option:: --tls-no-postpone-early-data

    By  default,   except  for  QUIC   connections,  nghttpx
    postpones forwarding  HTTP requests sent in  early data,
    including  those  sent in  partially  in  it, until  TLS
    handshake  finishes.  If  all backend  server recognizes
    "Early-Data"  header  field,  using  this  option  makes
    nghttpx  not postpone  forwarding request  and get  full
    potential of 0-RTT data.

.. option:: --tls-max-early-data=<SIZE>

    Sets  the  maximum  amount  of 0-RTT  data  that  server
    accepts.

    Default: ``16K``

.. option:: --tls-ktls

    Enable   ktls.    For   server,  ktls   is   enable   if
    :option:`--tls-session-cache-memcached` is not configured.


HTTP/2
~~~~~~

.. option:: -c, --frontend-http2-max-concurrent-streams=<N>

    Set the maximum number of  the concurrent streams in one
    frontend HTTP/2 session.

    Default: ``100``

.. option:: --backend-http2-max-concurrent-streams=<N>

    Set the maximum number of  the concurrent streams in one
    backend  HTTP/2 session.   This sets  maximum number  of
    concurrent opened pushed streams.  The maximum number of
    concurrent requests are set by a remote server.

    Default: ``100``

.. option:: --frontend-http2-window-size=<SIZE>

    Sets  the  per-stream  initial  window  size  of  HTTP/2
    frontend connection.

    Default: ``65535``

.. option:: --frontend-http2-connection-window-size=<SIZE>

    Sets the  per-connection window size of  HTTP/2 frontend
    connection.

    Default: ``65535``

.. option:: --backend-http2-window-size=<SIZE>

    Sets  the   initial  window   size  of   HTTP/2  backend
    connection.

    Default: ``65535``

.. option:: --backend-http2-connection-window-size=<SIZE>

    Sets the  per-connection window  size of  HTTP/2 backend
    connection.

    Default: ``2147483647``

.. option:: --http2-no-cookie-crumbling

    Don't crumble cookie header field.

.. option:: --padding=<N>

    Add  at most  <N> bytes  to  a HTTP/2  frame payload  as
    padding.  Specify 0 to  disable padding.  This option is
    meant for debugging purpose  and not intended to enhance
    protocol security.

.. option:: --no-server-push

    Disable HTTP/2 server push.  Server push is supported by
    default mode and HTTP/2  frontend via Link header field.
    It is  also supported if  both frontend and  backend are
    HTTP/2 in default mode.  In  this case, server push from
    backend session is relayed  to frontend, and server push
    via Link header field is also supported.

.. option:: --frontend-http2-optimize-write-buffer-size

    (Experimental) Enable write  buffer size optimization in
    frontend HTTP/2 TLS  connection.  This optimization aims
    to reduce  write buffer  size so  that it  only contains
    bytes  which can  send immediately.   This makes  server
    more responsive to prioritized HTTP/2 stream because the
    buffering  of lower  priority stream  is reduced.   This
    option is only effective on recent Linux platform.

.. option:: --frontend-http2-optimize-window-size

    (Experimental)   Automatically  tune   connection  level
    window size of frontend  HTTP/2 TLS connection.  If this
    feature is  enabled, connection window size  starts with
    the   default  window   size,   65535  bytes.    nghttpx
    automatically  adjusts connection  window size  based on
    TCP receiving  window size.  The maximum  window size is
    capped      by      the     value      specified      by
    :option:`--frontend-http2-connection-window-size`\.     Since   the
    stream is subject to stream level window size, it should
    be adjusted using :option:`--frontend-http2-window-size` option as
    well.   This option  is only  effective on  recent Linux
    platform.

.. option:: --frontend-http2-encoder-dynamic-table-size=<SIZE>

    Specify the maximum dynamic  table size of HPACK encoder
    in the frontend HTTP/2 connection.  The decoder (client)
    specifies  the maximum  dynamic table  size it  accepts.
    Then the negotiated dynamic table size is the minimum of
    this option value and the value which client specified.

    Default: ``4K``

.. option:: --frontend-http2-decoder-dynamic-table-size=<SIZE>

    Specify the maximum dynamic  table size of HPACK decoder
    in the frontend HTTP/2 connection.

    Default: ``4K``

.. option:: --backend-http2-encoder-dynamic-table-size=<SIZE>

    Specify the maximum dynamic  table size of HPACK encoder
    in the backend HTTP/2 connection.  The decoder (backend)
    specifies  the maximum  dynamic table  size it  accepts.
    Then the negotiated dynamic table size is the minimum of
    this option value and the value which backend specified.

    Default: ``4K``

.. option:: --backend-http2-decoder-dynamic-table-size=<SIZE>

    Specify the maximum dynamic  table size of HPACK decoder
    in the backend HTTP/2 connection.

    Default: ``4K``


Mode
~~~~

.. describe:: (default mode)

    
    Accept  HTTP/2,  and  HTTP/1.1 over  SSL/TLS.   "no-tls"
    parameter is  used in  :option:`--frontend` option,  accept HTTP/2
    and HTTP/1.1 over cleartext  TCP.  The incoming HTTP/1.1
    connection  can  be  upgraded  to  HTTP/2  through  HTTP
    Upgrade.

.. option:: -s, --http2-proxy

    Like default mode, but enable forward proxy.  This is so
    called HTTP/2 proxy mode.


Logging
~~~~~~~

.. option:: -L, --log-level=<LEVEL>

    Set the severity  level of log output.   <LEVEL> must be
    one of INFO, NOTICE, WARN, ERROR and FATAL.

    Default: ``NOTICE``

.. option:: --accesslog-file=<PATH>

    Set path to write access log.  To reopen file, send USR1
    signal to nghttpx.

.. option:: --accesslog-syslog

    Send  access log  to syslog.   If this  option is  used,
    :option:`--accesslog-file` option is ignored.

.. option:: --accesslog-format=<FORMAT>

    Specify  format  string  for access  log.   The  default
    format is combined format.   The following variables are
    available:

    * $remote_addr: client IP address.
    * $time_local: local time in Common Log format.
    * $time_iso8601: local time in ISO 8601 format.
    * $request: HTTP request line.
    * $status: HTTP response status code.
    * $body_bytes_sent: the  number of bytes sent  to client
      as response body.
    * $http_<VAR>: value of HTTP  request header <VAR> where
      '_' in <VAR> is replaced with '-'.
    * $remote_port: client  port.
    * $server_port: server port.
    * $request_time: request processing time in seconds with
      milliseconds resolution.
    * $pid: PID of the running process.
    * $alpn: ALPN identifier of the protocol which generates
      the response.   For HTTP/1,  ALPN is  always http/1.1,
      regardless of minor version.
    * $tls_cipher: cipher used for SSL/TLS connection.
    * $tls_client_fingerprint_sha256: SHA-256 fingerprint of
      client certificate.
    * $tls_client_fingerprint_sha1:  SHA-1   fingerprint  of
      client certificate.
    * $tls_client_subject_name:   subject  name   in  client
      certificate.
    * $tls_client_issuer_name:   issuer   name   in   client
      certificate.
    * $tls_client_serial:    serial    number   in    client
      certificate.
    * $tls_protocol: protocol for SSL/TLS connection.
    * $tls_session_id: session ID for SSL/TLS connection.
    * $tls_session_reused:  "r"   if  SSL/TLS   session  was
      reused.  Otherwise, "."
    * $tls_sni: SNI server name for SSL/TLS connection.
    * $backend_host:  backend  host   used  to  fulfill  the
      request.  "-" if backend host is not available.
    * $backend_port:  backend  port   used  to  fulfill  the
      request.  "-" if backend host is not available.
    * $method: HTTP method
    * $path:  Request  path  including query.   For  CONNECT
      request, authority is recorded.
    * $path_without_query:  $path   up  to  the   first  '?'
      character.    For   CONNECT  request,   authority   is
      recorded.
    * $protocol_version:   HTTP  version   (e.g.,  HTTP/1.1,
      HTTP/2)

    The  variable  can  be  enclosed  by  "{"  and  "}"  for
    disambiguation (e.g., ${remote_addr}).


    Default: ``$remote_addr - - [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"``

.. option:: --accesslog-write-early

    Write  access  log  when   response  header  fields  are
    received   from  backend   rather   than  when   request
    transaction finishes.

.. option:: --errorlog-file=<PATH>

    Set path to write error  log.  To reopen file, send USR1
    signal  to nghttpx.   stderr will  be redirected  to the
    error log file unless :option:`--errorlog-syslog` is used.

    Default: ``/dev/stderr``

.. option:: --errorlog-syslog

    Send  error log  to  syslog.  If  this  option is  used,
    :option:`--errorlog-file` option is ignored.

.. option:: --syslog-facility=<FACILITY>

    Set syslog facility to <FACILITY>.

    Default: ``daemon``


HTTP
~~~~

.. option:: --add-x-forwarded-for

    Append  X-Forwarded-For header  field to  the downstream
    request.

.. option:: --strip-incoming-x-forwarded-for

    Strip X-Forwarded-For  header field from  inbound client
    requests.

.. option:: --no-add-x-forwarded-proto

    Don't append  additional X-Forwarded-Proto  header field
    to  the   backend  request.   If  inbound   client  sets
    X-Forwarded-Proto,                                   and
    :option:`--no-strip-incoming-x-forwarded-proto`  option  is  used,
    they are passed to the backend.

.. option:: --no-strip-incoming-x-forwarded-proto

    Don't strip X-Forwarded-Proto  header field from inbound
    client requests.

.. option:: --add-forwarded=<LIST>

    Append RFC  7239 Forwarded header field  with parameters
    specified in comma delimited list <LIST>.  The supported
    parameters  are "by",  "for", "host",  and "proto".   By
    default,  the value  of  "by" and  "for" parameters  are
    obfuscated     string.     See     :option:`--forwarded-by`    and
    :option:`--forwarded-for` options respectively.  Note that nghttpx
    does  not  translate non-standard  X-Forwarded-\*  header
    fields into Forwarded header field, and vice versa.

.. option:: --strip-incoming-forwarded

    Strip  Forwarded   header  field  from   inbound  client
    requests.

.. option:: --forwarded-by=(obfuscated|ip|<VALUE>)

    Specify the parameter value sent out with "by" parameter
    of Forwarded  header field.   If "obfuscated"  is given,
    the string is randomly generated at startup.  If "ip" is
    given,   the  interface   address  of   the  connection,
    including port number, is  sent with "by" parameter.  In
    case of UNIX domain  socket, "localhost" is used instead
    of address and  port.  User can also  specify the static
    obfuscated string.  The limitation is that it must start
    with   "_",  and   only   consists   of  character   set
    [A-Za-z0-9._-], as described in RFC 7239.

    Default: ``obfuscated``

.. option:: --forwarded-for=(obfuscated|ip)

    Specify  the   parameter  value  sent  out   with  "for"
    parameter of Forwarded header field.  If "obfuscated" is
    given, the string is  randomly generated for each client
    connection.  If "ip" is given, the remote client address
    of  the connection,  without port  number, is  sent with
    "for"  parameter.   In  case   of  UNIX  domain  socket,
    "localhost" is used instead of address.

    Default: ``obfuscated``

.. option:: --no-via

    Don't append to  Via header field.  If  Via header field
    is received, it is left unaltered.

.. option:: --no-strip-incoming-early-data

    Don't strip Early-Data header  field from inbound client
    requests.

.. option:: --no-location-rewrite

    Don't  rewrite location  header field  in default  mode.
    When :option:`--http2-proxy`  is used, location header  field will
    not be altered regardless of this option.

.. option:: --host-rewrite

    Rewrite  host and  :authority header  fields in  default
    mode.  When  :option:`--http2-proxy` is  used, these  headers will
    not be altered regardless of this option.

.. option:: --altsvc=<PROTOID,PORT[,HOST,[ORIGIN[,PARAMS]]]>

    Specify   protocol  ID,   port,  host   and  origin   of
    alternative service.  <HOST>,  <ORIGIN> and <PARAMS> are
    optional.   Empty <HOST>  and <ORIGIN>  are allowed  and
    they  are treated  as  nothing is  specified.  They  are
    advertised  in alt-svc  header  field  only in  HTTP/1.1
    frontend.   This option  can be  used multiple  times to
    specify multiple alternative services.
    Example: :option:`--altsvc`\="h2,443,,,ma=3600; persist=1"

.. option:: --http2-altsvc=<PROTOID,PORT[,HOST,[ORIGIN[,PARAMS]]]>

    Just like :option:`--altsvc` option, but  this altsvc is only sent
    in HTTP/2 frontend.

.. option:: --add-request-header=<HEADER>

    Specify additional header field to add to request header
    set.   The field  name must  be lowercase.   This option
    just  appends header  field and  won't replace  anything
    already set.  This  option can be used  several times to
    specify multiple header fields.
    Example: :option:`--add-request-header`\="foo: bar"

.. option:: --add-response-header=<HEADER>

    Specify  additional  header  field to  add  to  response
    header  set.  The  field name  must be  lowercase.  This
    option  just  appends  header field  and  won't  replace
    anything already  set.  This option can  be used several
    times to specify multiple header fields.
    Example: :option:`--add-response-header`\="foo: bar"

.. option:: --request-header-field-buffer=<SIZE>

    Set maximum buffer size for incoming HTTP request header
    field list.  This is the sum of header name and value in
    bytes.   If  trailer  fields  exist,  they  are  counted
    towards this number.

    Default: ``64K``

.. option:: --max-request-header-fields=<N>

    Set  maximum  number  of incoming  HTTP  request  header
    fields.   If  trailer  fields exist,  they  are  counted
    towards this number.

    Default: ``100``

.. option:: --response-header-field-buffer=<SIZE>

    Set  maximum  buffer  size for  incoming  HTTP  response
    header field list.   This is the sum of  header name and
    value  in  bytes.  If  trailer  fields  exist, they  are
    counted towards this number.

    Default: ``64K``

.. option:: --max-response-header-fields=<N>

    Set  maximum number  of  incoming  HTTP response  header
    fields.   If  trailer  fields exist,  they  are  counted
    towards this number.

    Default: ``500``

.. option:: --error-page=(<CODE>|*)=<PATH>

    Set file path  to custom error page  served when nghttpx
    originally  generates  HTTP  error status  code  <CODE>.
    <CODE> must be greater than or equal to 400, and at most
    599.  If "\*"  is used instead of <CODE>,  it matches all
    HTTP  status  code.  If  error  status  code comes  from
    backend server, the custom error pages are not used.

.. option:: --server-name=<NAME>

    Change server response header field value to <NAME>.

    Default: ``nghttpx``

.. option:: --no-server-rewrite

    Don't rewrite server header field in default mode.  When
    :option:`--http2-proxy` is used, these headers will not be altered
    regardless of this option.

.. option:: --redirect-https-port=<PORT>

    Specify the port number which appears in Location header
    field  when  redirect  to  HTTPS  URI  is  made  due  to
    "redirect-if-not-tls" parameter in :option:`--backend` option.

    Default: ``443``

.. option:: --require-http-scheme

    Always require http or https scheme in HTTP request.  It
    also  requires that  https scheme  must be  used for  an
    encrypted  connection.  Otherwise,  http scheme  must be
    used.   This   option  is   recommended  for   a  server
    deployment which directly faces clients and the services
    it provides only require http or https scheme.


API
~~~

.. option:: --api-max-request-body=<SIZE>

    Set the maximum size of request body for API request.

    Default: ``32M``


DNS
~~~

.. option:: --dns-cache-timeout=<DURATION>

    Set duration that cached DNS results remain valid.  Note
    that nghttpx caches the unsuccessful results as well.

    Default: ``10s``

.. option:: --dns-lookup-timeout=<DURATION>

    Set timeout that  DNS server is given to  respond to the
    initial  DNS  query.  For  the  2nd  and later  queries,
    server is  given time based  on this timeout, and  it is
    scaled linearly.

    Default: ``5s``

.. option:: --dns-max-try=<N>

    Set the number of DNS query before nghttpx gives up name
    lookup.

    Default: ``2``

.. option:: --frontend-max-requests=<N>

    The number  of requests that single  frontend connection
    can process.  For HTTP/2, this  is the number of streams
    in  one  HTTP/2 connection.   For  HTTP/1,  this is  the
    number of keep alive requests.  This is hint to nghttpx,
    and it  may allow additional few  requests.  The default
    value is unlimited.


Debug
~~~~~

.. option:: --frontend-http2-dump-request-header=<PATH>

    Dumps request headers received by HTTP/2 frontend to the
    file denoted  in <PATH>.  The  output is done  in HTTP/1
    header field format and each header block is followed by
    an empty line.  This option  is not thread safe and MUST
    NOT be used with option :option:`-n`\<N>, where <N> >= 2.

.. option:: --frontend-http2-dump-response-header=<PATH>

    Dumps response headers sent  from HTTP/2 frontend to the
    file denoted  in <PATH>.  The  output is done  in HTTP/1
    header field format and each header block is followed by
    an empty line.  This option  is not thread safe and MUST
    NOT be used with option :option:`-n`\<N>, where <N> >= 2.

.. option:: -o, --frontend-frame-debug

    Print HTTP/2 frames in  frontend to stderr.  This option
    is  not thread  safe and  MUST NOT  be used  with option
    :option:`-n`\=N, where N >= 2.


Process
~~~~~~~

.. option:: -D, --daemon

    Run in a background.  If :option:`-D` is used, the current working
    directory is changed to '*/*'.

.. option:: --pid-file=<PATH>

    Set path to save PID of this program.

.. option:: --user=<USER>

    Run this program as <USER>.   This option is intended to
    be used to drop root privileges.

.. option:: --single-process

    Run this program in a  single process mode for debugging
    purpose.  Without this option,  nghttpx creates at least
    2 processes: main and  worker processes.  If this option
    is  used, main  and  worker are  unified  into a  single
    process.   nghttpx still  spawns  additional process  if
    neverbleed  is used.   In the  single process  mode, the
    signal handling feature is disabled.

.. option:: --max-worker-processes=<N>

    The maximum number of  worker processes.  nghttpx spawns
    new worker  process when  it reloads  its configuration.
    The previous worker  process enters graceful termination
    period and will terminate  when it finishes handling the
    existing    connections.     However,    if    reloading
    configurations  happen   very  frequently,   the  worker
    processes might be piled up if they take a bit long time
    to finish  the existing connections.  With  this option,
    if  the number  of  worker processes  exceeds the  given
    value,   the  oldest   worker   process  is   terminated
    immediately.  Specifying 0 means no  limit and it is the
    default behaviour.

.. option:: --worker-process-grace-shutdown-period=<DURATION>

    Maximum  period  for  a   worker  process  to  terminate
    gracefully.  When  a worker  process enters  in graceful
    shutdown   period  (e.g.,   when  nghttpx   reloads  its
    configuration)  and  it  does not  finish  handling  the
    existing connections in the given  period of time, it is
    immediately terminated.  Specifying 0 means no limit and
    it is the default behaviour.


Scripting
~~~~~~~~~

.. option:: --mruby-file=<PATH>

    Set mruby script file

.. option:: --ignore-per-pattern-mruby-error

    Ignore mruby compile error  for per-pattern mruby script
    file.  If error  occurred, it is treated as  if no mruby
    file were specified for the pattern.


HTTP/3 and QUIC
~~~~~~~~~~~~~~~

.. option:: --frontend-quic-idle-timeout=<DURATION>

    Specify an idle timeout for QUIC connection.

    Default: ``30s``

.. option:: --frontend-quic-debug-log

    Output QUIC debug log to */dev/stderr.*

.. option:: --quic-bpf-program-file=<PATH>

    Specify a path to  eBPF program file reuseport_kern.o to
    direct  an  incoming  QUIC  UDP datagram  to  a  correct
    socket.

    Default: ``/usr/local/lib/nghttp2/reuseport_kern.o``

.. option:: --frontend-quic-early-data

    Enable early data on frontend QUIC connections.  nghttpx
    sends "Early-Data" header field to a backend server if a
    request is received in early  data and handshake has not
    finished.  All backend servers should deal with possibly
    replayed requests.

.. option:: --frontend-quic-qlog-dir=<DIR>

    Specify a  directory where  a qlog  file is  written for
    frontend QUIC  connections.  A qlog file  is created per
    each QUIC  connection.  The  file name is  ISO8601 basic
    format, followed by "-", server Source Connection ID and
    ".sqlog".

.. option:: --frontend-quic-require-token

    Require an address validation  token for a frontend QUIC
    connection.   Server sends  a token  in Retry  packet or
    NEW_TOKEN frame in the previous connection.

.. option:: --frontend-quic-congestion-controller=<CC>

    Specify a congestion controller algorithm for a frontend
    QUIC  connection.   <CC>  should be  either  "cubic"  or
    "bbr".

    Default: ``cubic``

.. option:: --frontend-quic-secret-file=<PATH>

    Path to file that contains secure random data to be used
    as QUIC keying materials.  It is used to derive keys for
    encrypting tokens and Connection IDs.  It is not used to
    encrypt  QUIC  packets.  Each  line  of  this file  must
    contain  exactly  136  bytes  hex-encoded  string  (when
    decoded the byte string is  68 bytes long).  The first 3
    bits of  decoded byte  string are  used to  identify the
    keying material.  An  empty line or a  line which starts
    '#'  is ignored.   The file  can contain  more than  one
    keying materials.  Because the  identifier is 3 bits, at
    most 8 keying materials are  read and the remaining data
    is discarded.  The first keying  material in the file is
    primarily  used for  encryption and  decryption for  new
    connection.  The other ones are used to decrypt data for
    the  existing connections.   Specifying multiple  keying
    materials enables  key rotation.   Please note  that key
    rotation  does  not  occur automatically.   User  should
    update  files  or  change  options  values  and  restart
    nghttpx gracefully.   If opening  or reading  given file
    fails, all loaded keying  materials are discarded and it
    is treated as if none of  this option is given.  If this
    option is not  given or an error  occurred while opening
    or  reading  a  file,  a keying  material  is  generated
    internally on startup and reload.

.. option:: --quic-server-id=<HEXSTRING>

    Specify server  ID encoded in Connection  ID to identify
    this  particular  server  instance.   Connection  ID  is
    encrypted and  this part is  not visible in  public.  It
    must be 4  bytes long and must be encoded  in hex string
    (which is 8  bytes long).  If this option  is omitted, a
    random   server  ID   is   generated   on  startup   and
    configuration reload.

.. option:: --frontend-quic-initial-rtt=<DURATION>

    Specify the initial RTT of the frontend QUIC connection.

    Default: ``333ms``

.. option:: --no-quic-bpf

    Disable eBPF.

.. option:: --frontend-http3-window-size=<SIZE>

    Sets  the  per-stream  initial  window  size  of  HTTP/3
    frontend connection.

    Default: ``256K``

.. option:: --frontend-http3-connection-window-size=<SIZE>

    Sets the  per-connection window size of  HTTP/3 frontend
    connection.

    Default: ``1M``

.. option:: --frontend-http3-max-window-size=<SIZE>

    Sets  the  maximum  per-stream  window  size  of  HTTP/3
    frontend connection.  The window  size is adjusted based
    on the receiving rate of stream data.  The initial value
    is the  value specified  by :option:`--frontend-http3-window-size`
    and the window size grows up to <SIZE> bytes.

    Default: ``6M``

.. option:: --frontend-http3-max-connection-window-size=<SIZE>

    Sets the  maximum per-connection  window size  of HTTP/3
    frontend connection.  The window  size is adjusted based
    on the receiving rate of stream data.  The initial value
    is         the         value        specified         by
    :option:`--frontend-http3-connection-window-size`  and the  window
    size grows up to <SIZE> bytes.

    Default: ``8M``

.. option:: --frontend-http3-max-concurrent-streams=<N>

    Set the maximum number of  the concurrent streams in one
    frontend HTTP/3 connection.

    Default: ``100``


Misc
~~~~

.. option:: --conf=<PATH>

    Load  configuration  from   <PATH>.   Please  note  that
    nghttpx always  tries to read the  default configuration
    file if :option:`--conf` is not given.

    Default: ``/etc/nghttpx/nghttpx.conf``

.. option:: --include=<PATH>

    Load additional configurations from <PATH>.  File <PATH>
    is  read  when  configuration  parser  encountered  this
    option.  This option can be used multiple times, or even
    recursively.

.. option:: -v, --version

    Print version and exit.

.. option:: -h, --help

    Print this help and exit.



The <SIZE> argument is an integer and an optional unit (e.g., 10K is
10 * 1024).  Units are K, M and G (powers of 1024).

The <DURATION> argument is an integer and an optional unit (e.g., 1s
is 1 second and 500ms is 500 milliseconds).  Units are h, m, s or ms
(hours, minutes, seconds and milliseconds, respectively).  If a unit
is omitted, a second is used as unit.

FILES
-----

*/etc/nghttpx/nghttpx.conf*
  The default configuration file path nghttpx searches at startup.
  The configuration file path can be changed using :option:`--conf`
  option.

  Those lines which are staring ``#`` are treated as comment.

  The option name in the configuration file is the long command-line
  option name with leading ``--`` stripped (e.g., ``frontend``).  Put
  ``=`` between option name and value.  Don't put extra leading or
  trailing spaces.

  When specifying arguments including characters which have special
  meaning to a shell, we usually use quotes so that shell does not
  interpret them.  When writing this configuration file, quotes for
  this purpose must not be used.  For example, specify additional
  request header field, do this:

  .. code-block:: text

    add-request-header=foo: bar

  instead of:

  .. code-block:: text

    add-request-header="foo: bar"

  The options which do not take argument in the command-line *take*
  argument in the configuration file.  Specify ``yes`` as an argument
  (e.g., ``http2-proxy=yes``).  If other string is given, it is
  ignored.

  To specify private key and certificate file which are given as
  positional arguments in command-line, use ``private-key-file`` and
  ``certificate-file``.

  :option:`--conf` option cannot be used in the configuration file and
  will be ignored if specified.

Error log
  Error log is written to stderr by default.  It can be configured
  using :option:`--errorlog-file`.  The format of log message is as
  follows:

  <datetime> <main-pid> <current-pid> <thread-id> <level> (<filename>:<line>) <msg>

  <datetime>
    It is a combination of date and time when the log is written.  It
    is in ISO 8601 format.

  <main-pid>
    It is a main process ID.

  <current-pid>
    It is a process ID which writes this log.

  <thread-id>
    It is a thread ID which writes this log.  It would be unique
    within <current-pid>.

  <filename> and <line>
    They are source file name, and line number which produce this log.

  <msg>
    It is a log message body.

SIGNALS
-------

SIGQUIT
  Shutdown gracefully.  First accept pending connections and stop
  accepting connection.  After all connections are handled, nghttpx
  exits.

SIGHUP
  Reload configuration file given in :option:`--conf`.

SIGUSR1
  Reopen log files.

SIGUSR2

  Fork and execute nghttpx.  It will execute the binary in the same
  path with same command-line arguments and environment variables.  As
  of nghttpx version 1.20.0, the new main process sends SIGQUIT to the
  original main process when it is ready to serve requests.  For the
  earlier versions of nghttpx, user has to send SIGQUIT to the
  original main process.

  The difference between SIGUSR2 (+ SIGQUIT) and SIGHUP is that former
  is usually used to execute new binary, and the main process is newly
  spawned.  On the other hand, the latter just reloads configuration
  file, and the same main process continues to exist.

.. note::

  nghttpx consists of multiple processes: one process for processing
  these signals, and another one for processing requests.  The former
  spawns the latter.  The former is called main process, and the
  latter is called worker process.  If neverbleed is enabled, the
  worker process spawns neverbleed daemon process which does RSA key
  processing.  The above signal must be sent to the main process.  If
  the other processes received one of them, it is ignored.  This
  behaviour of these processes may change in the future release.  In
  other words, in the future release, the processes other than main
  process may terminate upon the reception of these signals.
  Therefore these signals should not be sent to the processes other
  than main process.

SERVER PUSH
-----------

nghttpx supports HTTP/2 server push in default mode with Link header
field.  nghttpx looks for Link header field (`RFC 5988
<http://tools.ietf.org/html/rfc5988>`_) in response headers from
backend server and extracts URI-reference with parameter
``rel=preload`` (see `preload
<http://w3c.github.io/preload/#interoperability-with-http-link-header>`_)
and pushes those URIs to the frontend client. Here is a sample Link
header field to initiate server push:

.. code-block:: text

  Link: </fonts/font.woff>; rel=preload
  Link: </css/theme.css>; rel=preload

Currently, the following restriction is applied for server push:

1. The associated stream must have method "GET" or "POST".  The
   associated stream's status code must be 200.

This limitation may be loosened in the future release.

nghttpx also supports server push if both frontend and backend are
HTTP/2 in default mode.  In this case, in addition to server push via
Link header field, server push from backend is forwarded to frontend
HTTP/2 session.

HTTP/2 server push will be disabled if :option:`--http2-proxy` is
used.

UNIX DOMAIN SOCKET
------------------

nghttpx supports UNIX domain socket with a filename for both frontend
and backend connections.

Please note that current nghttpx implementation does not delete a
socket with a filename.  And on start up, if nghttpx detects that the
specified socket already exists in the file system, nghttpx first
deletes it.  However, if SIGUSR2 is used to execute new binary and
both old and new configurations use same filename, new binary does not
delete the socket and continues to use it.

OCSP STAPLING
-------------

OCSP query is done using external Python script
``fetch-ocsp-response``, which has been originally developed in Perl
as part of h2o project (https://github.com/h2o/h2o), and was
translated into Python.

The script file is usually installed under
``$(prefix)/share/nghttp2/`` directory.  The actual path to script can
be customized using :option:`--fetch-ocsp-response-file` option.

If OCSP query is failed, previous OCSP response, if any, is continued
to be used.

:option:`--fetch-ocsp-response-file` option provides wide range of
possibility to manage OCSP response.  It can take an arbitrary script
or executable.  The requirement is that it supports the command-line
interface of ``fetch-ocsp-response`` script, and it must return a
valid DER encoded OCSP response on success.  It must return exit code
0 on success, and 75 for temporary error, and the other error code for
generic failure.  For large cluster of servers, it is not efficient
for each server to perform OCSP query using ``fetch-ocsp-response``.
Instead, you can retrieve OCSP response in some way, and store it in a
disk or a shared database.  Then specify a program in
:option:`--fetch-ocsp-response-file` to fetch it from those stores.
This could provide a way to share the OCSP response between fleet of
servers, and also any OCSP query strategy can be applied which may be
beyond the ability of nghttpx itself or ``fetch-ocsp-response``
script.

TLS SESSION RESUMPTION
----------------------

nghttpx supports TLS session resumption through both session ID and
session ticket.

SESSION ID RESUMPTION
~~~~~~~~~~~~~~~~~~~~~

By default, session ID is shared by all worker threads.

If :option:`--tls-session-cache-memcached` is given, nghttpx will
insert serialized session data to memcached with
``nghttpx:tls-session-cache:`` + lowercase hex string of session ID
as a memcached entry key, with expiry time 12 hours.  Session timeout
is set to 12 hours.

By default, connections to memcached server are not encrypted.  To
enable encryption, use ``tls`` keyword in
:option:`--tls-session-cache-memcached` option.

TLS SESSION TICKET RESUMPTION
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

By default, session ticket is shared by all worker threads.  The
automatic key rotation is also enabled by default.  Every an hour, new
encryption key is generated, and previous encryption key becomes
decryption only key.  We set session timeout to 12 hours, and thus we
keep at most 12 keys.

If :option:`--tls-ticket-key-memcached` is given, encryption keys are
retrieved from memcached.  nghttpx just reads keys from memcached; one
has to deploy key generator program to update keys frequently (e.g.,
every 1 hour).  The example key generator tlsticketupdate.go is
available under contrib directory in nghttp2 archive.  The memcached
entry key is ``nghttpx:tls-ticket-key``.  The data format stored in
memcached is the binary format described below:

.. code-block:: text

    +--------------+-------+----------------+
    | VERSION (4)  |LEN (2)|KEY(48 or 80) ...
    +--------------+-------+----------------+
                   ^                        |
		   |                        |
		   +------------------------+
                   (LEN, KEY) pair can be repeated

All numbers in the above figure is bytes.  All integer fields are
network byte order.

First 4 bytes integer VERSION field, which must be 1.  The 2 bytes
integer LEN field gives the length of following KEY field, which
contains key.  If :option:`--tls-ticket-key-cipher`\=aes-128-cbc is
used, LEN must be 48.  If
:option:`--tls-ticket-key-cipher`\=aes-256-cbc is used, LEN must be
80.  LEN and KEY pair can be repeated multiple times to store multiple
keys.  The key appeared first is used as encryption key.  All the
remaining keys are used as decryption only.

By default, connections to memcached server are not encrypted.  To
enable encryption, use ``tls`` keyword in
:option:`--tls-ticket-key-memcached` option.

If :option:`--tls-ticket-key-file` is given, encryption key is read
from the given file.  In this case, nghttpx does not rotate key
automatically.  To rotate key, one has to restart nghttpx (see
SIGNALS).

CERTIFICATE TRANSPARENCY
------------------------

nghttpx supports TLS ``signed_certificate_timestamp`` extension (`RFC
6962 <https://tools.ietf.org/html/rfc6962>`_).  The relevant options
are :option:`--tls-sct-dir` and ``sct-dir`` parameter in
:option:`--subcert`.  They takes a directory, and nghttpx reads all
files whose extension is ``.sct`` under the directory.  The ``*.sct``
files are encoded as ``SignedCertificateTimestamp`` struct described
in `section 3.2 of RFC 69662
<https://tools.ietf.org/html/rfc6962#section-3.2>`_.  This format is
the same one used by `nginx-ct
<https://github.com/grahamedgecombe/nginx-ct>`_ and `mod_ssl_ct
<https://httpd.apache.org/docs/trunk/mod/mod_ssl_ct.html>`_.
`ct-submit <https://github.com/grahamedgecombe/ct-submit>`_ can be
used to submit certificates to log servers, and obtain the
``SignedCertificateTimestamp`` struct which can be used with nghttpx.

MRUBY SCRIPTING
---------------

.. warning::

  The current mruby extension API is experimental and not frozen.  The
  API is subject to change in the future release.

.. warning::

  Almost all string value returned from method, or attribute is a
  fresh new mruby string, which involves memory allocation, and
  copies.  Therefore, it is strongly recommended to store a return
  value in a local variable, and use it, instead of calling method or
  accessing attribute repeatedly.

nghttpx allows users to extend its capability using mruby scripts.
nghttpx has 2 hook points to execute mruby script: request phase and
response phase.  The request phase hook is invoked after all request
header fields are received from client.  The response phase hook is
invoked after all response header fields are received from backend
server.  These hooks allows users to modify header fields, or common
HTTP variables, like authority or request path, and even return custom
response without forwarding request to backend servers.

There are 2 levels of mruby script invocations: global and
per-pattern.  The global mruby script is set by :option:`--mruby-file`
option and is called for all requests.  The per-pattern mruby script
is set by "mruby" parameter in :option:`-b` option.  It is invoked for
a request which matches the particular pattern.  The order of hook
invocation is: global request phase hook, per-pattern request phase
hook, per-pattern response phase hook, and finally global response
phase hook.  If a hook returns a response, any later hooks are not
invoked.  The global request hook is invoked before the pattern
matching is made and changing request path may affect the pattern
matching.

Please note that request and response hooks of per-pattern mruby
script for a single request might not come from the same script.  This
might happen after a request hook is executed, backend failed for some
reason, and at the same time, backend configuration is replaced by API
request, and then the request uses new configuration on retry.  The
response hook from new configuration, if it is specified, will be
invoked.

The all mruby script will be evaluated once per thread on startup, and
it must instantiate object and evaluate it as the return value (e.g.,
``App.new``).  This object is called app object.  If app object
defines ``on_req`` method, it is called with :rb:class:`Nghttpx::Env`
object on request hook.  Similarly, if app object defines ``on_resp``
method, it is called with :rb:class:`Nghttpx::Env` object on response
hook.  For each method invocation, user can can access
:rb:class:`Nghttpx::Request` and :rb:class:`Nghttpx::Response` objects
via :rb:attr:`Nghttpx::Env#req` and :rb:attr:`Nghttpx::Env#resp`
respectively.

.. rb:module:: Nghttpx

.. rb:const:: REQUEST_PHASE

    Constant to represent request phase.

.. rb:const:: RESPONSE_PHASE

    Constant to represent response phase.

.. rb:class:: Env

    Object to represent current request specific context.

    .. rb:attr_reader:: req

        Return :rb:class:`Request` object.

    .. rb:attr_reader:: resp

        Return :rb:class:`Response` object.

    .. rb:attr_reader:: ctx

        Return Ruby hash object.  It persists until request finishes.
        So values set in request phase hook can be retrieved in
        response phase hook.

    .. rb:attr_reader:: phase

        Return the current phase.

    .. rb:attr_reader:: remote_addr

        Return IP address of a remote client.  If connection is made
        via UNIX domain socket, this returns the string "localhost".

    .. rb:attr_reader:: server_addr

        Return address of server that accepted the connection.  This
	is a string which specified in :option:`--frontend` option,
	excluding port number, and not a resolved IP address.  For
	UNIX domain socket, this is a path to UNIX domain socket.

    .. rb:attr_reader:: server_port

        Return port number of the server frontend which accepted the
        connection from client.

    .. rb:attr_reader:: tls_used

        Return true if TLS is used on the connection.

    .. rb:attr_reader:: tls_sni

        Return the TLS SNI value which client sent in this connection.

    .. rb:attr_reader:: tls_client_fingerprint_sha256

        Return the SHA-256 fingerprint of a client certificate.

    .. rb:attr_reader:: tls_client_fingerprint_sha1

        Return the SHA-1 fingerprint of a client certificate.

    .. rb:attr_reader:: tls_client_issuer_name

        Return the issuer name of a client certificate.

    .. rb:attr_reader:: tls_client_subject_name

        Return the subject name of a client certificate.

    .. rb:attr_reader:: tls_client_serial

        Return the serial number of a client certificate.

    .. rb:attr_reader:: tls_client_not_before

        Return the start date of a client certificate in seconds since
        the epoch.

    .. rb:attr_reader:: tls_client_not_after

        Return the end date of a client certificate in seconds since
        the epoch.

    .. rb:attr_reader:: tls_cipher

        Return a TLS cipher negotiated in this connection.

    .. rb:attr_reader:: tls_protocol

        Return a TLS protocol version negotiated in this connection.

    .. rb:attr_reader:: tls_session_id

        Return a session ID for this connection in hex string.

    .. rb:attr_reader:: tls_session_reused

        Return true if, and only if a SSL/TLS session is reused.

    .. rb:attr_reader:: alpn

        Return ALPN identifier negotiated in this connection.

    .. rb:attr_reader:: tls_handshake_finished

        Return true if SSL/TLS handshake has finished.  If it returns
        false in the request phase hook, the request is received in
        TLSv1.3 early data (0-RTT) and might be vulnerable to the
        replay attack.  nghttpx will send Early-Data header field to
        backend servers to indicate this.

.. rb:class:: Request

    Object to represent request from client.  The modification to
    Request object is allowed only in request phase hook.

    .. rb:attr_reader:: http_version_major

        Return HTTP major version.

    .. rb:attr_reader:: http_version_minor

        Return HTTP minor version.

    .. rb:attr_accessor:: method

        HTTP method.  On assignment, copy of given value is assigned.
        We don't accept arbitrary method name.  We will document them
        later, but well known methods, like GET, PUT and POST, are all
        supported.

    .. rb:attr_accessor:: authority

        Authority (i.e., example.org), including optional port
        component .  On assignment, copy of given value is assigned.

    .. rb:attr_accessor:: scheme

        Scheme (i.e., http, https).  On assignment, copy of given
        value is assigned.

    .. rb:attr_accessor:: path

        Request path, including query component (i.e., /index.html).
        On assignment, copy of given value is assigned.  The path does
        not include authority component of URI.  This may include
        query component.  nghttpx makes certain normalization for
        path.  It decodes percent-encoding for unreserved characters
        (see https://tools.ietf.org/html/rfc3986#section-2.3), and
        resolves ".." and ".".  But it may leave characters which
        should be percent-encoded as is. So be careful when comparing
        path against desired string.

    .. rb:attr_reader:: headers

        Return Ruby hash containing copy of request header fields.
        Changing values in returned hash does not change request
        header fields actually used in request processing.  Use
        :rb:meth:`Nghttpx::Request#add_header` or
        :rb:meth:`Nghttpx::Request#set_header` to change request
        header fields.

    .. rb:method:: add_header(key, value)

        Add header entry associated with key.  The value can be single
        string or array of string.  It does not replace any existing
        values associated with key.

    .. rb:method:: set_header(key, value)

        Set header entry associated with key.  The value can be single
        string or array of string.  It replaces any existing values
        associated with key.

    .. rb:method:: clear_headers

        Clear all existing request header fields.

    .. rb:method:: push(uri)

        Initiate to push resource identified by *uri*.  Only HTTP/2
        protocol supports this feature.  For the other protocols, this
        method is noop.  *uri* can be absolute URI, absolute path or
        relative path to the current request.  For absolute or
        relative path, scheme and authority are inherited from the
        current request.  Currently, method is always GET.  nghttpx
        will issue request to backend servers to fulfill this request.
        The request and response phase hooks will be called for pushed
        resource as well.

.. rb:class:: Response

    Object to represent response from backend server.

    .. rb:attr_reader:: http_version_major

        Return HTTP major version.

    .. rb:attr_reader:: http_version_minor

        Return HTTP minor version.

    .. rb:attr_accessor:: status

        HTTP status code.  It must be in the range [200, 999],
        inclusive.  The non-final status code is not supported in
        mruby scripting at the moment.

    .. rb:attr_reader:: headers

        Return Ruby hash containing copy of response header fields.
        Changing values in returned hash does not change response
        header fields actually used in response processing.  Use
        :rb:meth:`Nghttpx::Response#add_header` or
        :rb:meth:`Nghttpx::Response#set_header` to change response
        header fields.

    .. rb:method:: add_header(key, value)

        Add header entry associated with key.  The value can be single
        string or array of string.  It does not replace any existing
        values associated with key.

    .. rb:method:: set_header(key, value)

        Set header entry associated with key.  The value can be single
        string or array of string.  It replaces any existing values
        associated with key.

    .. rb:method:: clear_headers

        Clear all existing response header fields.

    .. rb:method:: return(body)

        Return custom response *body* to a client.  When this method
        is called in request phase hook, the request is not forwarded
        to the backend, and response phase hook for this request will
        not be invoked.  When this method is called in response phase
        hook, response from backend server is canceled and discarded.
        The status code and response header fields should be set
        before using this method.  To set status code, use
        :rb:attr:`Nghttpx::Response#status`.  If status code is not
        set, 200 is used.  To set response header fields,
        :rb:meth:`Nghttpx::Response#add_header` and
        :rb:meth:`Nghttpx::Response#set_header`.  When this method is
        invoked in response phase hook, the response headers are
        filled with the ones received from backend server.  To send
        completely custom header fields, first call
        :rb:meth:`Nghttpx::Response#clear_headers` to erase all
        existing header fields, and then add required header fields.
        It is an error to call this method twice for a given request.

    .. rb:method:: send_info(status, headers)

        Send non-final (informational) response to a client.  *status*
        must be in the range [100, 199], inclusive.  *headers* is a
        hash containing response header fields.  Its key must be a
        string, and the associated value must be either string or
        array of strings.  Since this is not a final response, even if
        this method is invoked, request is still forwarded to a
        backend unless :rb:meth:`Nghttpx::Response#return` is called.
        This method can be called multiple times.  It cannot be called
        after :rb:meth:`Nghttpx::Response#return` is called.

MRUBY EXAMPLES
~~~~~~~~~~~~~~

Modify request path:

.. code-block:: ruby

    class App
      def on_req(env)
        env.req.path = "/apps#{env.req.path}"
      end
    end

    App.new

Don't forget to instantiate and evaluate object at the last line.

Restrict permission of viewing a content to a specific client
addresses:

.. code-block:: ruby

    class App
      def on_req(env)
        allowed_clients = ["127.0.0.1", "::1"]

        if env.req.path.start_with?("/log/") &&
           !allowed_clients.include?(env.remote_addr) then
          env.resp.status = 404
          env.resp.return "permission denied"
        end
      end
    end

    App.new

API ENDPOINTS
-------------

nghttpx exposes API endpoints to manipulate it via HTTP based API.  By
default, API endpoint is disabled.  To enable it, add a dedicated
frontend for API using :option:`--frontend` option with "api"
parameter.  All requests which come from this frontend address, will
be treated as API request.

The response is normally JSON dictionary, and at least includes the
following keys:

status
  The status of the request processing.  The following values are
  defined:

  Success
    The request was successful.

  Failure
    The request was failed.  No change has been made.

code
  HTTP status code

Additionally, depending on the API endpoint, ``data`` key may be
present, and its value contains the API endpoint specific data.

We wrote "normally", since nghttpx may return ordinal HTML response in
some cases where the error has occurred before reaching API endpoint
(e.g., header field is too large).

The following section describes available API endpoints.

POST /api/v1beta1/backendconfig
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This API replaces the current backend server settings with the
requested ones.  The request method should be POST, but PUT is also
acceptable.  The request body must be nghttpx configuration file
format.  For configuration file format, see `FILES`_ section.  The
line separator inside the request body must be single LF (0x0A).
Currently, only :option:`backend <--backend>` option is parsed, the
others are simply ignored.  The semantics of this API is replace the
current backend with the backend options in request body.  Describe
the desired set of backend severs, and nghttpx makes it happen.  If
there is no :option:`backend <--backend>` option is found in request
body, the current set of backend is replaced with the :option:`backend
<--backend>` option's default value, which is ``127.0.0.1,80``.

The replacement is done instantly without breaking existing
connections or requests.  It also avoids any process creation as is
the case with hot swapping with signals.

The one limitation is that only numeric IP address is allowed in
:option:`backend <--backend>` in request body unless "dns" parameter
is used while non numeric hostname is allowed in command-line or
configuration file is read using :option:`--conf`.

GET /api/v1beta1/configrevision
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This API returns configuration revision of the current nghttpx.  The
configuration revision is opaque string, and it changes after each
reloading by SIGHUP.  With this API, an external application knows
that whether nghttpx has finished reloading its configuration by
comparing the configuration revisions between before and after
reloading.  It is recommended to disable persistent (keep-alive)
connection for this purpose in order to avoid to send a request using
the reused connection which may bound to an old process.

This API returns response including ``data`` key.  Its value is JSON
object, and it contains at least the following key:

configRevision
  The configuration revision of the current nghttpx


SEE ALSO
--------

:manpage:`nghttp(1)`, :manpage:`nghttpd(1)`, :manpage:`h2load(1)`