eaiovnaovbqoebvqoeavibavo doc/freetds/ea-freetds-1.4.9/NEWS.md000064400000075053147633065420012555 0ustar00$Id: 4d8b89247d1fb609bbe1761c3c1a430b125e76ba $ Summary of Changes in release 1.4 -------------------------------------------- User visible (not in a particular order): - Fix some numeric conversion checks; - Always use Unicode for SSPI allowing not ASCII to work; - Improve BCP copy, especially for Sybase; - Better error reporting for ICONV failures; - Disable TLSv1 by default; - ODBC: partial TVP support (missing data at execution); - ODBC: support for quoted string in connection string; - CT-Library: support large identifiers; - CT-Library: report appropriate severity values; - apps: datacopy report errors on standard error; - pool: use poll instead of select to support more connections. Implementation: - Use more bool type for boolean instead of integer; - more macros for ODBC tests to encapsulate some ODBC API. Summary of Changes in release 1.3 -------------------------------------------- User visible (not in a particular order): - Generic: - Support UTF-8 columns using MSSQL 2019; - Do not accept TDS protocol versions "4.6" (never really supported) and "8.0"; - Minor portability issues; - Fix log elision for login; - Detect some possible minor memory failure in application; - Support long (more than 64k) SSPI packets (never encountered but you never know); - Fix unicode columns for ASA database; - Avoid using BCP with old protocols; - (\*) Fix bulk copy using big endian machines; - (\*) Fix Sybase uni(var)char and unsigned types for big endian machines; - (\*) Do not send nullable data during bulk copy if type is not nullable; - ODBC: - Added "Timeout" setting; - Applications: - Improve defncopy utility: - Fix some declaration; - Fix Sybase support; - (\*) Fix datacopy and freebcp logging ; - CT-Library: - Minor fix for variant type; - Better support for timeout setting; - (\*) Support some missing types (like nullable unsigned integers) for Sybase; - DB-library: - Unify date format (all systems can use the same syntax); - (\*) Allows to pass 0 as type for bcp_bind; - (\*) Fix DBSETLSERVERPRINCIPAL macro; - (\*) Do not limit queries length for bcp using Sybase; - (\*) Add KEEP_NULLS to BCP hints. (\*) Feature backported in stable 1.2 branch. Implementation: - Move replacement headers under freetds directory for coherence with other internal headers; - Lot of style updates; - Optimize UTF-8 encoding for ODBC, reuse common code. Summary of Changes in release 1.2 -------------------------------------------- User visible (not in a particular order): - Sybase server: - All strings are now converted as MSSQL; - Support kerberos login; - DB-Library: add DBSETNETWORKAUTH, DBSETMUTUALAUTH, DBSETDELEGATION and DBSETSERVERPRINCIPAL; - CT-Library: add CS_SEC_NETWORKAUTH, CS_SEC_NETWORKAUTH, CS_SEC_NETWORKAUTH and CS_SEC_NETWORKAUTH; - Bulk copies: - DB-Library: fix trim of unicode fields; - (\*) Apply character conversion for Sybase, like MSSQL; - (\*) Ignore computed columns; - (\*) Properly support multibyte strings in column names; - (\*) DB-Library: stop correctly on BCPMAXERRS setting; - (\*) DB-Library: do not try to convert skipped rows reading file allowing for instance to load CVS files; - (\*) CT-Library: added CS_DATABASE property to allows to connect correctly to Azure servers; - (\*) Improve support for MS XML columns for both DB-Library and CT-Library; - (\*) Fix some issues with MSSQL server redirection (used for instance in Azure); - (\*) Change SQL_DESC_OCTET_LENGTH value for wise character columns; - Better support for SQL_VARIANT: - Better column checks; - (\*) CT-Library: now supported, columns are returned as CS_CHAR_TYPE; - Some updates to server part: - Set correctly initial state; - IPv6 support; - Fix TDS 7.2 logins; - Support extended character using domain logins under Unix; - Improve MARS: - Less memory copies; - (\*) Remove possible deadlock; - Handle wrapping sequence/window numbers; - Make sure we sent the wanted packet; - (\*) Support UTF-16 surrogate pairs in odbc_wide2utf and odbc_set_string_flag fixing some character encoding support; - (\*) Fix multiple queries, used by ODBC to optimize data load; - (\*) Improve emulated parameter queries, fixing minor issues and reducing memory usage; - Support DBVERSION_UNKNOWN in dbsetlversion (will use automatic detection); - CT-Library: define CS_MIN_SYBTYPE and CS_MAX_SYBTYPE; - (\*) CT-Library: fix cs_will_convert accepting library constants, not libTDS. (\*) Feature backported in stable 1.1 branch. Implementation: - User guide converted to XML; - Always use little endian on network level, simpler and faster; - Converted some files to markdown; - Optimize bytes endianess conversion; - Made character lookup faster making character conversion quicker; - Optimize data padding in CT-Library; - Fix some build dependencies causing some files to not be properly recompiled during development; - Add "freeze" support allowing to pause sending in order to simplify lengths computations sending data. Summary of Changes in release 1.1 -------------------------------------------- User visible (not in a particular order): - Changed default TDS protocol version during configure to "auto". Versions 4.2 and 7.0 are no longer accepted for default, you may still specify an explicit version to connect to obsolete servers ("auto" won't attempt these versions); - allows to disable TLS 1.0 support; - pool server allows to specify different username/password for server and clients allowing to hide internal server logins; - tsql utility now send final partial query to server to avoid to have to specify a final "GO" line to terminate commands; - better support for Microsoft cluster, client will attempt multiple connection to server at the same time if DNS reply multiple IPs; - MONEY/SMALLMONEY types are now formated with 4 decimal digits to avoid truncation; - MARS support is now compiled by default; - pool server is now compiled by default; - Fixed SQL_ATTR_LOGIN_TIMEOUT for ODBC; - Fixed large integer numbers for ODBC RPC constants; - Fixed encrypted logins if "auto" protocol version is used; - Support CS_TIMEOUT, CS_LOGIN_TIMEOUT and CS_CLIENTCHARSET properties under CTLibrary; - Added a dbacolname function in DBLibrary, similar to dbcolname but for compute columns (mainly for Sybase now, Microsoft removed support for compute columns); - NTLMv2 is now on by default. Implementation: - Improved UTF-8 performances; - Use more stdint.h style definitions (like uint32_t); - Use bool type instead of int; - pool server compile under Windows too (not as capable as Unix version); - CMake build is now able to do an installation; - Added a src/utils directory to collect all common code not strictly related to replacements or TDS; - Simplified makefiles; - Support CP1252 encoding in internal trivial iconv; - Better ODBC detection. Allows to specify a directory with --with-iodbc to specify custom iOBDC. Summary of Changes in release 1.0 -------------------------------------------- User visible (not in a particular order): - Removed "8.0" from protocol version string accepted. Please update configuration files; - Default protocol version is now auto. This could slow down connection but make user experience less painful; - Sybase encrypted login. Set encryption to get it; - Support protocol version 7.4; - Add intent support to specify we don't want to change data; - Allow to attach database file during the login (MS SQL Server); - Support for Sybase time/date/bigdate/bigdatetime; - Pool is working again; - ODBC BCP (not complete); - Improved dbconvert and dbconvert_ps (more compatible); - Fixed dbspid; - Improved ODBC type information; - Better certificate verification; - AppVeyor is used for every build; - Try all IPs from DNS. This allows SQL Cluster connection to secondary servers. Implementation: - Removed Nmake support; - Type conversions simplified; - Better type handle code. Summary of Changes in release 0.95 -------------------------------------------- User visible (not in a particular order): - Support for build with CMake under Windows. - Support MSSQL 2008: - new date/time types; - NBCROWs; - able to retrieve CLR UDT types in binary format. - Moved from CVS to git. - Support MARS under ODBC. - IPv6 support. - Support unsigned Sybase types. - Sybase use some characters conversion like MSSQL. - Bulk-copy improvements: - more types; - support for empty fields; - no needs for seekable file; - avoid possible buffer overflows; - less memory consumption; - handle different BIT fields in Sybase; - -T option for datacopy. - datacopy: - prompting for password (use "-" password on command line); - empty user/password (to use Kerberos). - Support for query notifications in ODBC. - Support for protocols 7.2 and 7.3 under dblib and ctlib. - dblib: - dbpivot extension; - dbprcollen extension to get printable column size; - add DBCOL2 structure for dbtablecolinfo; - support DBTEXTSIZE option for dbsetopt; - support SRCNUMERICBIND and SRCDECIMALBIND binding; - DATETIME2BIND extension binding to support new mssql 2008 type; - ODBC: - add SQL_INFO_FREETDS_TDS_VERSION option to SQLGetInfo to retrieve FreeTDS version; - add --enable-odbc-wide-tests configure option to use wide functions in unit tests. - Better thread support. - Allow to specify server SPN for GSSAPI. - Sybase graceful disconnects. - Better support for VARCHAR(MAX)/VARBINARY(MAX). - Better error reporting from login failure. - More strict test for configuration errors, fails if configuration is wrong. - "use utf-16" option to enable use of UTF-16 for server encoding (MSSQL). - Remove support for Dev-C++. - Remove support for bad iconv, use libiconv instead (Tru64 and HP-UX should be affected), connect will fail. - New NTLM options: - "use lanman"; - "use ntlmv2". - New Kerberos options: - "realm" ("REALM" in ODBC); - "spn" ("ServerSPN" in ODBC). - New certificate options: - "ca file"; - "crl file"; - "check certificate hostname". - Many bug fixes, majors: - SSPI with Kerberos on some setup; - SQLCancel threading; - ctlib numeric; - ODBC statistic function quotings. Implementation: - Introdude streams support to make easier handling large data and making conversions faster. - Use array of flags to make faster to retrieve data type features. - Use callbacks for handling various type functions. - Optimize data conversions. - Store TDS packets in a new structure to handle multiple packets. - New DSTR implementation which use less memory. - Faster logging. - Put mostly data handling in src/tds/data.c. - Move mostly headers to include/freetds directory. - Add a include/freetds/proto.h header to separate protocol declarations. - Add src/tds/packet.c to separate code handling TDS packets. - Modify libTDS error codes, not only TDS_FAIL. - Use DSTR for names in TDSCOLUMN. - Generate graphs in Doxygen. Summary of Changes in release 0.91 -------------------------------------------- 1. Full Kerberos and SSPI support for passwordless login to Microsoft SQL Server from Unix and Windows clients. Includes Kerberos delegation option. 2. Full support for DB-Library under Win32/64 via NMAKE.EXE. 3. Built-in support for UTF-8. 4. Support for wide characters in ODBC. 5. Support for varchar(max) and varbinary(max). 6. Better thread-safety in ODBC. 7. Distinguish between connect and login errors. 8. Bulk-copy functions in CT-Library. TDS versions now reflect Microsoft's nomenclature. The previous version numbers (8.0 and 9.0) are now 7.1 and 7.2. See the UG for details. Executive Summary of Changes in release 0.82 -------------------------------------------- 1. timeout handling 2. encrypted connections 3. fisql (and odbc utilities) 4. autoconf improvements 5. 23,710 lines added or deleted (101,022 total). 6. 85 files added 7. 21 unit tests added Details ------- db-lib - timeouts work! - corrected dbnextrow - implemented dbsetnull and dbsetinterrupt - improved error reporting and checking - fixed rpc parameter processing, now php works correctly ct-lib - added cs_loc_alloc, cs_loc_drop, cs_locale implementations odbc - cursors (mssql) - fixed database setting - return error always if odbc returns SQL_ERROR - fixed SQLGetData result utilities - added support for NUL characters inside terminators in freebcp - added row termination and column termination option to tsql - new fisql application - new ODBC utilities documentation - significant updates to TDS protocol documentation - freetds.conf man page - added tenderfoot sample code general - fixed timeout handling - added freetds.conf option for encryption - added protocol version discovery - NTLM2 session response - read table and real column name from wire - experimental Kerberos support using gssapi - some optimizations for GCC4 - optimized conversions avoiding some memory copy - minor improves to server stuff - improved MingW compile (even cross one) - more verbose log for dblib and odbc - many test added 1 test for libTDS 1 test for ctlib 3 tests for dblib 13 tests for odbc libTDS API changes - tds_add_row_column_size removed - tds_alloc_row return now TDS_SUCCEED/TDS_FAIL - tds_alloc_compute_row return now TDS_SUCCEED/TDS_FAIL - removed TDSCOLUMN->column_offset - added TDSCOLUMN->column_data and TDSCOLUMN->column_data_free - added TDSCURSOR->type and TDSCURSOR->concurrency for mssql support - added fetch_type and i_row parameters to tds_cursor_fetch - added tds_cursor_update and tds_cursor_setname functions - made tds_alloc_get_string static - removed tds_free_cursor - added TDSCURSOR->ref_count - added tds_cursor_deallocated and tds_release_cursor to handle cursor release. tds_cursor_deallocated is called when cursor got deallocated from server while tds_release_cursor is called to decrement reference counter. Reference counter is used cause is difficult to trace pointer owner between libTDS and upper libraries - added TDS_COMPILETIME_SETTINGS->sysconfdir - changed DSTR_STRUCT structure to include dstr_size - changed DSTR type - error handler cannot return TDS_INT_EXIT - removed TDSSOCKET->query_timeout_func TDSSOCKET->query_timeout_param, TDSSOCKET->query_start_time - changed TDSLOGIN->host_name to client_host_name - changed TDSCONNECTION->host_name to client_host_name - changed TDSLOGIN->encrypted to encryption_level - changed TDSCONNECTION->encrypted to encryption_level - added TDSRESULTINFO->row_free handler to free row - added TDSCONTEXT->int_handler handler - removed tds_prtype - removed tds_alloc_param_row - added tds_alloc_param_data - added flags parameter to tds7_send_auth - removed tds_client_msg - added tdserror to report error - added flags parameter to tds_answer_challenge - added is_variable_type macro - added TDSCOLUMN->table_column_name - added tds parameter to tds_set_column_type - renamed BCPCOLDATA->null_column to is_null - added TDSMESSAGE->oserr - remove length, number_upd_cols and cur_col_list from TDSCURSOR (never used) - added new TDSAUTHENTICATION to handle authentication modules - added TDSSOCKET->authentication - added tds_ntlm_get_auth and tds_gss_get_auth - removed TDSANSWER - removed tds7_send_auth (use new tds_ntlm_get_auth) - added tds_get_int8 - add TDSPARAMINFO *params argument to tds_cursor_declare - add TDSPARAMINFO *params argument to tds_cursor_open - changed TDSSOCKET->rows_affected from int to TDS_INT8 - added TDSSOCKET->tds9_transaction (used internally for TDS9) - added TDSCONNECTION->server_host_name needed for Kerberos support * 0.64 - core library - reduced network bandwidth use on Linux and *BSD - do not free TDSSOCKET in tds_connect - moved network stuff into net.c - fixed conversion NUMERIC->NUMERIC changing precision/scale - added named instance support (mssql2k) - fixed cancel and timeout - added support for encrypted connection using mssql (using either GnuTLS or OpenSSL) - improved numeric conversions performance - improved debug logging (added "debug flags" option) - ctlib - ct_dynamic and friends (placeholder support) - dblib - more functions - made threadsafe - improved bcp - support for large files using BCP - fixed buffering - ODBC - fixed compute handling in ODBC - paramset support - constant parameters in rpc (ie {?=call func(10,?)} ) - configure use automatically odbc_config if available - compatibility - improve PHP support - improve DBD::ODBC support - partial dos32 support - improve JDBC support - added msvc6 project to build dblib library on windows - support long password on tsql for all platforms - improved pool server - RPMs - ODBC driver registration (in odbcinst.ini) - better dependency for RedHat and SUSE - a lot of fixes libTDS API changes - tds_connect does not free TDSSOCKET* on failure - TDSSOCKET->env is not a pointer anymore - tds_free_compute_result and tds_free_compute_results are now static - added TDSDYNAMIC->next for linked list - removed TDSCURSOR->client_cursor_id - use TDSCURSOR* cursor instead of TDS_INT client_cursor_it in tds_cursor_* functions - added const char* file param to tdsdump_dump_buf and tdsdump_log and added line information in level - changed tds_alloc_compute_results declaration, pass a TDSSOCKET* - removed tds_do_until_done (not used) - removed tds_set_longquery_handler function (not used) - changed some fields in TDSSOCKET - removed out_len (not used) - renamed cursor to cursors - removed client_cursor_id - added cur_cursor (instead of removed client_cursor_id) - dyns now a pointer to a pointer to first dynamic allocated - removed num_dyns (now useless with linked list) - removed chkintr and hndlintr (use longquery_*) - removed longquery_timeout (use query_timeout) - renamed longquery_func to query_timeout_func - renamed longquery_param to query_timeout_param - queryStarttime to query_start_time - add a DSTR instance_name to TDSCONNECTION - add tds7_get_instance_port - removed tds_free_all_dynamic - tdsdump_append now static - new tds_process_tokens to replace removed - tds_process_result_tokens - tds_process_row_tokens - tds_process_row_tokens_ct - tds_process_trailing_tokens - removed tds_ctx_set_parent/tds_ctx_get_parent, use parent member - added void * parent argument to tds_alloc_context - tds_process_tokens return a TDS_CANCELLED if handle cancellation - removed query_timeout_func and query_timeout_param from TDSCONNECTION and TDSLOGIN - add tds_free_row - renamed TDSLOCALE->char_set to server_charset * 0.63 - ODBC: use tds_dstr* functions to store descriptor information - header privatizations (removing tds.h dependency). This is quite important for future binary compatibility. - ODBC: SQLFetch returns error correctly - ODBC: fix problem rebinding parameters - ODBC: ability to fetch data types after prepare (needed for Oracle bindings and OTL library). - Builds cleanly under OS X. - Improved BCP support for NULL fields and native file format. - ct-lib: ct_blk support (bcp for ct-lib). - ct-lib: Cursors! - apps: added bsqldb and defncopy. - iconv: better collation support, e.g. SQL_Scandinavian_CP850_CI_AS * 0.62 - ct-lib: cursor support - fixed PHP problem handling empty recordsets. See messages on ML: Damian Kramer, September 23, "Possible bug in freeTDS" Steve Hanselman, September 16 "Issue with freetds 0.61.2 ..." - ODBC: improved, best error report - ct-lib: support ct_diag (for Python) - ODBC: fixed SQLMoreResults/SQLRowCount and batch behavior - ODBC: fixes call to {?=store(?)} - ODBC: multiple record with "select id,name from sysobjects where name = 'sysobjects'" - ODBC: fixed early binding - ODBC: autodetect iODBC or unixODBC during configure - ODBC: implemented option 109 in SQLGetConnectOption (for OpenOffice) - freebcp understand \n as newline. Also \r and \0 (null byte). - added --without-libiconv configure option to switch off iconv library - ODBC: test and fixes for NUMERIC parameter - ODBC: dynamic query - SQLPutData - Sybase and blobs ported code for string building from ODBC to libtds - extended TDSSOCKET::iconv_info as an array. Keep converters for non-UCS-2 server charsets. Every TDSCOLINFO holding character data should point to one of these elements. - dblib: src/dblib/unittests/t0017.c (bcp) fixed - changed tds_get_char_data(), ML 2 May 2003, "tds_get_char_data and iconv". - rewrote tds_iconv: - use iconv() signature. - rely on TDSCOLINFO::iconv_info for conversion descriptor, instead of inferring it from the column sizes. - on read error, emit Msg 2403, Severity 16 (EX_INFO): "WARNING! Some character(s) could not be converted into client's character set. Unconverted bytes were changed to question marks ('?')." - on write error emit Msg 2402, Severity 16 (EX_USER): "Error converting client characters into server's character set. Some character(s) could not be converted." and return an error code. Do not proceed. - Cf. ML 16 Apr 2003. "conversion error management". - added doxygen to the nightly build - "make install" put the UG in PREFIX/share/doc/freetds/userguide - "make install" put doxygen html in PREFIX/share/doc/freetds/reference - moved website docs (not UG) to doc/htdoc, put in CVS - added bcp support to tds/dblib/ctlib. (started in dblib) - RPC stuff - added support for TDS 8.0 - TDS 7 Unicode to native charset conversion using iconv - autoconf the connection pooling stuff - DBLIB: output params - set database during login process - libtds: dynamic query - ctlib: null returns zero-length string (see "SELECT '' and TDS 7.0" in message list on 26 Jan 2003) * Jan 2003 - Version 0.61 - Dynamic SQL - Output parameters - Compute rows - Varbinary support - dsn-less ODBC connections - RPC support (db-lib) - Compatibility with DBD::Sybase 0.95 - 68 new functions! (see doc/api_status.txt) - Error/message handling rewritten, uses real error numbers - new sample programs - much cleaner code, warning-free compiles - namespace cleanup - public domain versions of functions for OSs that lack them - autoconf portability improvements - builds in HP-UX, Win32, and cygwin - No dependency on OpenSSL * Sep 2002 - Version 0.60 - Support for SQL Server 2000 datatypes and domain logins. - Support and convertibility of all major datatypes. - Much expanded coverage of the ODBC API. - An all-new BCP implementation, including host variable support. - Character set conversions, via the iconv library. - Threadsafe operation. * [late 2001?] - tdspool now working for big endian systems - Fixed mem leak in ctlib - Added some descriptive text to the PWD file - EINTR handling during login (Kostya Ivanov) - Added support for TLI style interfaces files (thanks Michael for explaining) - Added 'text size' config option which changes textsize on connect - Added preliminary TDS 8.0 support (no new datatypes supported though) - Added 'emulate little endian' config flag - Some TDS5 placeholder stuff. Not ready for primetime yet. - Fixed interfaces handling seg fault * Jul 2001 Brian Bruns - Version 0.52 - Mem leak fixes in dbloginfree() and tds_free_env() (John Dumas) - Added support for new configuration format (freetds.conf) - unixODBC now working - Fixed error in two's complement function for money types - Added support for nullable bits (BITN) - checked in work on tds connection pooling server - added preliminary userguide (James Lowden and me) - a lot of work on ODBC driver, now works with PHP - added config options for iodbc/unixodbc (unixODBC doesn't actually work yet) - image -> char now works (verified with ctlib only) - varbinary -> char now works with destlen of -1 - New config routines - Free socket on login fail - 64bit patches - off by one error - numeric problem with 7.0 fixed - digit cutoff on numerics/floats fixed * Nov 2000 Brian Bruns - Version 0.51 - removed all the old unittests from the samples directory - endian detection fixed - 'make check' and ctlib unittests (Mark) - TDS 7.0 fixes, numerics et al. (Scott) - dead connection handling (Geoff) - query timeout stuff (Jeff) * Dec 1999 Brian Bruns - Version 0.50 - Added TDS 7.0 support for MS SQL 7 - Added hostfile bulk copy for dblib - Added writetext support for dblib - Added CS_CON_STATUS property to ctlib - Fixed bugs for ctlib version of PHP 3/4 - Many changes to text/image handling - New script for running the unittests - dbcancel/ct_cancel now working properly - inserts/updates now return proper rowcount - Numerous bug fixes * Sep 1999 Brian Bruns - Version 0.47 - Added workaround for SQL 7.0 bug handling datetime/money for big endian (testing/bug report - Paul Schaap) - Added TDS 7.0 login function (untested) - Fixed many big endian bugs - Fixed some bus errors on Sparc - Fixed big endian detection - DBD::Sybase 0.19 now passes all tests - Fixed date bug working with PHP 3.x - binary/varbinary support added - Fixed Text datatypes in tds layer - More conversions implemented (Mark Schaal) - Fix make install for not overwriting interfaces (Michael Peppler) - CS_USERDATA now works - Numerous bug fixes (many people) * Thu Aug xx 1999 Brian Bruns - Version 0.46 - Fixed floating type support - Fixed lots of little datatype conversion bugs - Fixed 5.0 login acknowledgement bug - Message processing was cleaned up (Mark Schaal) - Fixed login bug for SQL Server 7.0 - DBD::Sybase 0.19 now compiles and partially works (very partially) - Fixed Solaris #define clash - Numerous bug fixes * Thu Jun 03 1999 Brian Bruns - Version 0.45 - Capabilities added to ctlib code - Numeric support working - MONEY to string conversions now support > 32 bit values - Fixed underread in message handling - Fixed various buffer overflow problems - Fixed NULL handling - Added support for length binding (copied arguement to ct_bind) - Converted ODBC to use iODBC driver manager - SQSH 1.7 runs - PHP 3.0.x with ctlib now runs * Thu Jan 14 1999 Brian Bruns - Version 0.41 - Better row buffering (Craig Spannring) - CT-Lib code improved greatly - Closer behaviour to real dblib - Commonized datatype conversions - Server side code is running somewhat. - SQSH 1.6 running - More ODBC functionality - Many bug fixes - Lots of other stuff I've already forgotten * Sun Nov 22 1998 Brian Bruns - Version 0.40 - Row buffering is now supported for dblib. - Better row handling (side effect of above) - Improved conversion code - Preliminary ODBC layer - PHP now runs basic scripts, maybe more - Many many bug fixes - General cleanup (better error handling, C++ friendly headers, etc...) * Fri Sep 04 1998 Mihai Ibanescu - Version 0.31 - By default the install dir is /usr/local/freetds - The Makefile in the samples dir is automatically built from Makefile.am. The samples dir is not installed, only packaged in the distribution. * Wed Sep 02 1998 Brian Bruns - Version 0.3 - Updated the AUTHORS file - FIXME Brian (added by misa) * Mon Aug 31 1998 Mihai Ibanescu - Version 0.21 - GNUified - Fixed a couple of the TODO issues: byte order is automatically determined, and the TDS version is a configurable option - Modified the README file to reflect the new directory structure Pre-GNUification log by Brian : 2/8/98 Should be able to send the first packet to a server soon, my output is only slightly different than open clients. This codes pretty crappy right now. I need to clean up alot of stuff, remove hardcode values, etc...but I'm anxious to see something work! 2/7/98 Broke the code up a bit, tds.c now handles all wire level stuff, dblib.c handles dblib specific stuff. So, in the future there can be ctlib.c and obdc.c can also sit on top of tds.c to handle the other CLIs 3/16/98 Been working on the code here and there...We can now send a query to the server, dbnumcols() and dbcolname() both work. Almost ready to get some data back. I put in a dummy dbbind to just handle strings so, I could do some work on dbnextrow(). However, we will have revisit almost everything later. 3/23/98 Haven't been able to work on it lately. Still trying to decide on the best way to propagate the row data from tds.c to dblib.c to the calling func. Not that hard, but nothing strikes me as the "Right Way" (tm). 4/2/98 Ok we are ready to release 0.01 (marked by the fact that a simple dblib program actually works!) 5/1/98 Haven't updated in quite a while. A few more dblib commands are supported. dbconvert() support is preliminary. Fixed alot of bugs. A little bit of cleanup. dbbind() sorta works now, needs work still. At least one mem leak that I know of (haven't gotten around to fixing it. Wish I had more time to work on it... 5/2/98 Decided to release what I have. executing sp_who seems to mostly work.. a step in the right direction. Version 0.02. Seem to have generated a little interest after mentioning it in a usenet post. 5/6/98 Can compile against sqsh!!! Did a reorg on tds.c, all dblib func that read data now go through tds_process_messages() which read the marker and calls other routines as necessary. sqsh's output is a little screwy (well I don't have a real dbprrow() yet, but the number of result sets coming back is too many). So, anyway Version 0.04 5/9/98 Decided to upload some new code, mostly just stubs. Sybperl compiles I can't get my perl to work with it. (I need to download perl and link statically, the one that comes on the system won't do). Anyway, most of dblib is present in stub form. 5/17/98 Managed to scrape up some time and release new code. Duplicate result sets went away, and handling of more datatypes (money, bit, more int stuff). Also, improved dbprhead()/row() function. 5/26/98 Ok, I'm doing the long overdue cleaning up of the code. All the kludges should be gone. Thanks, to everyone who contributed code/idea/corrections. 6/3/98 The majority of the overhaul is done...still some work to do, but this is much better than before. I'm bumping the version to 0.1 signifying that I actually use sqsh compiled against it on a regular basis. 6/5/98 TDS 4.2 support seems to be working properly 6/26/98 Gregg Jenson has added support for err and msg handling among other things. I've added some prelimary ctlib support (nothing working yet) 7/3/98 I think we are about ready to release 0.2. Gregg sent some datetime code which appears to work great. I added TDS 4.6 support (small changes really) and tested all the byte order issues on an RS/6000. Also, ctlib code will run the unittest.c and will compile all modules in sqsh 1.6, however there are many missing functions before it will link! 7/10/98 Haven't been able to work on it lately (moved this week). Anyway, trying to add some functions to server. 7/13/98 Tom Poindexter made some changes to get sybtcl to work. 8/8/98 Haven't had much time lately (again), however some small stuff has been fixed and the protocol version stuff has (mostly) been moved to a runtime option. sybperl is supposedly running for simple stuff. doc/freetds/ea-freetds-1.4.9/tds_ssl.html000064400000023002147633065420014003 0ustar00 SSL and TDS

How to enable encryption on MSSQL

Under Linux (or any system that have openssl)

# create a file containing key and self-signed certificate
openssl req \
  -x509 -nodes -days 365 \
  -newkey rsa:1024 -keyout mycert.pem -out mycert.pem

# export mycert.pem as PKCS#12 file, mycert.pfx
openssl pkcs12 -export \
  -out mycert.pfx -in mycert.pem \
  -name "My Certificate"

So we created a mycert.pfx certificate ready to be imported

Under Windows

Open MMC and add certificates snap-in, add our certificate under personal and under ca root (to validate it)

Add to the registry the thumbprint of our certificato so to be used by mssql. For examples 

REGEDIT4

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MSSQLServer\MSSQLServer\SuperSocketNetLib]
"Certificate"=hex:DD,5F,6C,EE,47,8E,0C,C0,74,8B,C4,71,8D,87,1C,E6,07,20,F2,28

Restart MSSQL

Check event viewer for results

Encryption protocol

Prelogin packet (tds 7.1 only)

>From client to server 

00000000  12 01 00 34 00 00 00 00  00 00 15 00 06 01 00 1b ...4.... ........
00000010  00 01 02 00 1c 00 0c 03  00 28 00 04 ff 08 00 01 ........ .(......
00000020  55 00 00 01 4d 53 53 51  4c 53 65 72 76 65 72 00 U...MSSQ LServer.
00000030  38 09 00 00                                      8...
HeaderDescriptionValue
00 00 15 00 06 netlib version (0) start from 0x15 length 0x06 8.341.0
01 00 1b 00 01 encrypt flag (1) start from 0x1b length 0x01 1, see below
02 00 1c 00 0c instance name (2) start from 0x1c length 0x0c "MSSQLServer\0" (as you note string is null terminated)
03 00 28 00 04 process id (3) start from 0x28 length 0x04 0x938 (why in little endian ??)
ff end  

Meaning of encryption flag (client):

  • 0x00 normal
  • 0x01 high encryption (128 bit ??)

MSSQL 2005 have 9.0.0 as a version and have a single byte option 4 (always seen as zero, I don't know the meaning).

>From server to client 

00000000  04 01 00 25 00 00 01 00  00 00 15 00 06 01 00 1b ...%.... ........
00000010  00 01 02 00 1c 00 01 03  00 1d 00 00 ff 08 00 02 ........ ........
00000020  f8 00 00 01 00

Similar
HeaderDescriptionValue
00 00 15 00 06 version (0) start from 0x15 length 0x06 8.0.760.0
01 00 1b 00 01 encrypt flag (1) start from 0x1b length 0x01 1, see below
02 00 1c 00 01 instance name (2) start from 0x1c length 0x01 "\0" (still null terminatted)
03 00 1d 00 00 process id (3) start from 0x1d length 0x0 no info
ff end  

Meaning of encryption flag (server):

  • 0x02, no certificate, no encryption required just do normal jobs (like FreeTDS)
  • 0x00, certificate, no force flag on server, prelogin to see certificate (TLS 1.0, not SSL 2 or 3 !!) login encrypted, after login do normal TDS (not encrypted)
  • 0x01, certificate, high encryption required by client prelogin to see certificate login encrypted, after login changed crypt (my client close connection perhaps a configuration problem...)
  • 0x03, certificate enabled, force encryption configured on server prelogin like 0x00, remains in SSL after login

Note that mssql2k unpatched do not set last packet flag (byte 2) for this packet.

Following a valid encrypted connection (0x00 from server, no force)

>From client to server 

00000034  12 01 00 46 00 00 00 00  16 03 01 00 39 01 00 00 ...F.... ....9...
00000044  35 03 01 41 b9 5e 02 f8  7d 45 81 31 d9 73 9e 93 5..A.^.. }E.1.s..
00000054  91 b2 dd f4 4a 80 a3 92  a8 0f aa 67 32 8a 72 6d ....J... ...g2.rm
00000064  4b 22 07 00 00 0e 00 09  00 64 00 62 00 03 00 06 K"...... .d.b....
00000074  00 12 00 63 01 00                                ...c..

prelogin packet (0x12), content TLS 1.0 (you can see a ClientHell0, see RFC 2246)

>From server to client 

00000025  04 01 03 da 00 00 01 00  16 03 01 03 cd 02 00 00 ........ ........
00000035  46 03 01 41 b9 5e 03 4b  c1 bf 9b a5 7d 83 74 57 F..A.^.K ....}.tW
00000045  00 03 de b5 fb fc 4d f8  84 15 ce 07 d9 ab fe 2b ......M. .......+
00000055  57 3c ad 20 96 10 00 00  6f 31 af e4 17 ae 2a 2b W<. .... o1....*+
00000065  37 29 0e 57 8a 4d 1d 32  aa d9 ed 62 6b 3d 3c d1 7).W.M.2 ...bk=<.
00000075  d1 c6 a9 cb 00 09 00 0b  00 03 7b 00 03 78 00 03 ........ ..{..x..
00000085  75 30 82 03 71 30 82 02  da a0 03 02 01 02 02 01 u0..q0.. ........
00000095  00 30 0d 06 09 2a 86 48  86 f7 0d 01 01 04 05 00 .0...*.H ........
000000A5  30 81 88 31 0b 30 09 06  03 55 04 06 13 02 49 54 0..1.0.. .U....IT
000000B5  31 10 30 0e 06 03 55 04  08 13 07 42 6f 6c 6f 67 1.0...U. ...Bolog
000000C5  6e 61 31 10 30 0e 06 03  55 04 07 13 07 42 6f 6c na1.0... U....Bol
... omissis...

normal reply packet (0x4), ServerHello(2), content TLS (certificate).

NOTE: if server send certificate request client (MS ODBC) crash so I think this is not supported.

>From client to server 

0000007A  12 01 00 c6 00 00 00 00  16 03 01 00 86 10 00 00 ........ ........
0000008A  82 00 80 3a c6 96 ba 55  ce 8e 4b a4 e2 d7 b7 bd ...:...U ..K.....
0000009A  5d 5e f4 28 30 c6 c7 b9  4e 66 60 80 45 ce cb 4e ]^.(0... Nf`.E..N
000000AA  f6 f7 91 d7 9b 05 79 f8  ad f7 c7 13 77 36 cb 8c ......y. ....w6..
000000BA  04 58 33 3f 51 c8 0a bb  6a 95 8f 65 a1 e9 74 c5 .X3?Q... j..e..t.
000000CA  c9 c6 4a 11 b1 36 87 84  f2 96 82 d0 19 8a dd dc ..J..6.. ........
000000DA  d1 32 6a 32 ab 73 47 76  58 69 16 fd 9f 0b bd d7 .2j2.sGv Xi......
000000EA  72 79 a7 86 9a 71 2b 70  9a d1 8f e2 54 63 46 81 ry...q+p ....TcF.
000000FA  3e 6d 8a f7 8d 2e 26 02  3f 2d 0c a1 bc 63 ac 0a >m....&. ?-...c..
0000010A  8a 38 0e 14 03 01 00 01  01 16 03 01 00 28 12 09 .8...... .....(..
0000011A  d5 2d 93 8c 60 aa ae ec  e3 9b 2b 3c 27 63 46 ad .-..`... ..+<'cF.
0000012A  b1 b9 3d 1e 06 60 18 49  6d bb 76 80 8b 7b 51 70 ..=..`.I m.v..{Qp
0000013A  b7 79 14 b8 ba 62                                .y...b

prelogin (0x12), still TLS handshake, client_key_exchange (??) (0x16, 0x10), change crypt (0x14), handshake (crypted)

>From server to client 

000003FF  04 01 00 3b 00 00 01 00  14 03 01 00 01 01 16 03 ...;.... ........
0000040F  01 00 28 96 3c 2e 41 42  09 d3 a8 77 82 19 7f 4b ..(.<.AB ...w...K
0000041F  ac 04 b8 96 4b f1 65 c2  35 9e ef 6a 1d c2 41 2d ....K.e. 5..j..A-
0000042F  a3 98 b8 2b 5c 0f 40 d1  98 b0 1e                ...+\.@. ...

normal reply (0x4), still TLS

0x14 means change crypt, followed by 0x16 (handshake crypted).

>From client to server 

00000140  17 03 01 01 08 d7 3a b5  c3 fd a7 4d 14 b7 ce c7 ......:. ...M....
00000150  c6 6f f3 c5 03 1c 5c 86  7b 15 98 45 2a 93 73 c7 .o....\. {..E*.s.
00000160  72 75 72 23 c2 11 20 7d  5c b1 be e7 ac 72 ac b3 rur#.. } \....r..
00000170  47 41 4f 45 d8 fa 22 2b  94 b1 67 a5 7f de af 96 GAOE.."+ ..g.....
00000180  05 ad bb fc e4 33 66 3a  a2 f1 8d c5 5f 84 8b 38 .....3f: ...._..8
00000190  86 b0 df e8 87 e7 2c 26  e6 c0 66 2e b1 53 86 40 ......,& ..f..S.@
000001A0  98 0d 9e 2f 49 0b 17 b2  9d 55 d3 e3 7e 08 ca b9 .../I... .U..~...
000001B0  de 62 87 23 14 98 6e 10  d0 dd c2 94 70 4c 33 4b .b.#..n. ....pL3K
000001C0  09 8d b8 46 e5 a2 31 52  4d 89 06 b2 10 a8 ed b0 ...F..1R M.......
000001D0  a8 21 02 79 ab 99 de 67  28 a3 6c ea 18 88 b5 63 .!.y...g (.l....c
000001E0  02 ab f4 a1 78 0d 83 ec  b6 7b 61 7d 42 d2 38 bb ....x... .{a}B.8.
000001F0  50 fc e1 9e 1e e0 51 69  93 ea 05 9f d5 a4 a8 2b P.....Qi .......+
00000200  18 7f 79 4f 29 1a c0 35  3c 55 83 b0 9f af b7 de ..yO)..5 <U......
00000210  6d 2d 12 fa 27 ef 28 6b  a9 83 12 e6 a1 09 58 00 m-..'.(k ......X.
00000220  30 b3 3d f0 60 00 97 84  ee 28 b0 ae 31 78 50 d7 0.=.`... .(..1xP.
00000230  85 82 19 9f 57 ca a6 1c  d2 81 0f 6b 2d fb 47 41 ....W... ...k-.GA
00000240  37 58 8a ba 4f 38 f6 00  23 24 56 c2 35          7X..O8.. #$V.5

Well... you can note that this it's not a TDS packet !!! This is a fully crypted packet (login packet).

>From server to client 

0000043A  04 01 01 79 00 33 01 00  e3 1b 00 01 06 6d 00 61 ...y.3.. .....m.a
0000044A  00 73 00 74 00 65 00 72  00 06 6d 00 61 00 73 00 .s.t.e.r ..m.a.s.
0000045A  74 00 65 00 72 00 ab 66  00 45 16 00 00 02 00 25 t.e.r..f .E.....%
0000046A  00 43 00 68 00 61 00 6e  00 67 00 65 00 64 00 20 .C.h.a.n .g.e.d. 
0000047A  00 64 00 61 00 74 00 61  00 62 00 61 00 73 00 65 .d.a.t.a .b.a.s.e
0000048A  00 20 00 63 00 6f 00 6e  00 74 00 65 00 78 00 74 . .c.o.n .t.e.x.t
0000049A  00 20 00 74 00 6f 00 20  00 27 00 6d 00 61 00 73 . .t.o.  .'.m.a.s
... omissis ...

Now normal data follow. In this case server used flag 0 (see above).

With force login (0x03 from server) after crypted login packet server and client continue to keep encrypting full packets

Note that uncrypted packets are still splitted using packet size selected during login (that is usually 4096 bytes). doc/freetds/ea-freetds-1.4.9/TODO.md000064400000013327147633065420012542 0ustar00To Do List ========== This list is ordered top-to-bottom by priority. Things that are broken and need mending are at the top, followed by things that should work before the next release, followed by features that should be added/fixed/reworked (grouped by library). Everyone is encouraged to add to the list. Developers can do it directly; anyone else can post a patch to SourceForge. In this way we can communicate with each other about the project's priorities and needs. Must be fixed: ==== * ctlib parameters, handle all case even in tds7 * handle and test prepared query (? and @ syntax should be supported) * cancellation * ctlib seems to hang reading row while in IDLE state (tds_peek if not in pending state hang... update) Applied but could not test fix from ML 21 May 2008: "Problem with FreeTDS validating SQL commands (actually a ct_cancel() error)" I don't know if this is still true. Upper libraries should not use tds_peek as it does handle cancellation. Work in progress: ==== * be able to disable iconv for BCP (see Sybase documentation) I have a patch to disable it, how to handle NVARCHAR? -- freddy77 * BCP under ODBC. There is an experimental patch trying to implement it. For future versions (in priority order within library): All ---- * Cache protocol discovery (TDSVER=0.0). Save port/instance into some permanent storage. tsql should report progress in verbose mode. * retain values used from freetds.conf, so we can report them. * add a way for tsql to report host, port, and TDS version for the connection it's attempting. Actually libTDS does the name resolution in tds_connect and then just connect so there is no way for tsql to report these information. * move error message macro/prototype to tds.h.in; use in dblib.c. * conversion from ucs2 to utf8, provide for 2+ bytes/character * change numeric format to improve performance ?? * little/big endian based on platform * already packet at word * correctly aligned to read directly packetized * limit copy of data (now wire -> tds -> temp -> client) use a method like zero-copy In token.c getting row should write data even to client (callback, new user types, see ctlib conversion functions) In query.c writing data do the same (use additional column fields?) Situation is much improved in 0.95 version. In ODBC is much better as wire -> tds are never performed and convert extension to give client buffer is used if possible so to avoid the temp step. * review the way parameters are packed (too complicate, see ctlib bulk, cf "bulk copy and row buffer") * improve cursor support on dblib and ctlib * read on partial packet, do not wait entire one * detect if realloc accepts NULL pointers (in configure.ac) * support for password longer than 30 characters under Sybase (anybody know how ??) * under Sybase using prepared statements and BLOBs we shouldn't try to prepare every time (cache failure preparing, see odbc unittests logs, binary_test) done in ODBC ?? * Native bcp has no iconv support; character bcp files are assumed be encoded with the client's charset. More flexibility one both sides would be good. * date/time on Sybase (from 12.5) * encrypted connection for Sybase db-lib ---- * add DBTEXTLIMIT (dbsetopt), PHP require it to support textlimit ini value ct-lib ---- * dynamic placeholders (DBD::Sybase) * ct_option() calls (CS_OPT_ROWCOUNT, CS_OPT_TEXTSIZE, among others) * async function, async calls (dbpoll() and friends) * support all type of bind in ct_bind (CS_VARBINARY_TYPE and other) search "site:.sybase.com CS_VARBINARY ct_bind" on google for more info * complete sqlstate and other field in message (for Python) odbc ---- * SQLDescribeParam (Sybase seems to require it) A 100% success for DBD::ODBC require this. Require parsing of the string to extract placeholders ("?") type, something like "INSERT INTO test_table(field_a) VALUES(?)" -> "SELECT field_a FROM test_table(NOLOCK) WHERE 0=1" * Star Office complains that these TypeInfo constants are not implemented in SQLGetInfo: 47 SQL_USER_NAME (handle environment callbacks) do a "SELECT USER_NAME()". If data pending MS do another connection with same login. * SQLNativeSql and fill SQLGetInfo according (mssql7+ handle odbc escapes directly) * it seems that if statement it's wrong and we issue SQLPrepare on SQLExecute it try to send unprepared dynamic... state on dynamic?? * odbc array binding test large field (like image) have language queries some limits? do we have to split large multiple queries? * report error just before returning SQL_ERROR from inner function? * handle async flags ?? * handle no termination on odbc_set_string* Test and fix ---- * hidden fields (FOR BROWSE select, see flag test on tds) * what happen if we bind to an hidden field?? * if we use SQLGetData?? * if we request informations with SQLDescribeCol/SQLColAttribute(s)/ SQLGetDescField?? * as you noted returning # columns hidden fields are not counted (there is however a setting which is a mssql extension which threat hidden columns as normal) (cfr "SQLNumResultCols() is wrong (+1)" Jan 8 2008) * test: descriptors work * what happen to SQL_DESC_DATETIME_INTERVAL_CODE and SQL_DESC_CONCISE_TYPE changing only SQL_DESC_TYPE (with SQLSetDescField) * test: set SQL_C_DEFAULT and call SQLFetch (numeric, others) * test: SQLGetStmtAttr(SQL_ATTR_ROW_NUMBER) * all binded parameters * no bind and sqlgetdata * before first fetch * after last fetch pool ---- * get connection pooling working with all protocol versions * Make pool configuration a non-recompile process server ---- * Server API needs more work. It's in a quite ugly state. It's more experimental. Should be disabled by default to state it. doc/freetds/ea-freetds-1.4.9/tds.html000064400000144024147633065420013132 0ustar00 TDS Protocol Documentation

TDS Protocol Documentation

This document attempts to cover the TDS protocol for:

TDS VersionSupported Products
4.2Sybase SQL Server < 10 and Microsoft SQL Server 6.5
5.0Sybase SQL Server >= 10
7.0Microsoft SQL Server 7.0
7.1Microsoft SQL Server 2000
7.2Microsoft SQL Server 2005

Contents

Common Terms

TDS protocol versions
  TDS 5.0    tds version 5.0
  TDS 7.0    tds version 7.0
  TDS 7.0+   tds version 7.0, 7.1 and 7.2
  TDS 5.0-   tds version 5.0 and previous

Variable types used in this document:
  CHAR      8-bit char
    CHAR[6]	string of 6 chars
    CHAR[n]     variable length string
  XCHAR    single byte (TDS 5.0-) or ucs2le (TDS 7.0+) characters
  INT8      8-bit int
  INT16    16-bit int
  INT32    32-bit int
  UCS2LE   Unicode in UCS2LE format

Note: FreeTDS uses TDS_TINYINT for INT8 and TDS_SMALLINT for INT16.

Typical Usage sequences

These are TDS 4.2 and not meant to be 100% correct, but I thought they might be helpful to get an overall view of what goes on. 

--> Login
<-- Login acknowledgement

--> INSERT SQL statement
<-- Result Set Done

--> SELECT SQL statement
<-- Column Names
<-- Column Info
<-- Row Result
<-- Row Result
<-- Result Set Done

--> call stored procedure
<-- Column Names
<-- Column Info
<-- Row Result
<-- Row Result
<-- Done Inside Process
<-- Column Names
<-- Column Info
<-- Row Result
<-- Row Result
<-- Done Inside Process
<-- Return Status
<-- Process Done

The packet format

Every informations in TDS protocol (query, RPCs, responses and so on) is splitted in packets.

All packets start with the following 8 byte header. 

 INT8       INT8          INT16      4 bytes
+----------+-------------+----------+--------------------+
|  packet  | last packet |  packet  |    unknown         |
|   type   |  indicator  |   size   |                    |
+----------+-------------+----------+--------------------+

Fields:
packet type 
     0x01 TDS 4.2 or 7.0 query
     0x02 TDS 4.2 or 5.0 login packet
     0x03 RPC
     0x04 responses from server
     0x06 cancels
     0x07 Used in Bulk Copy
     0x0F TDS 5.0 query
     0x10 TDS 7.0 login packet
     0x11 TDS 7.0 authentication packet
     0x12 TDS 8 prelogin packet
last packet indicator 
     0x00 if more packets
     0x01 if last packet
packet size
     (in network byte order)
unknown?
     always 0x00
     this has something to do with server to server communication/rpc stuff

The remainder of the packet depends on the type of information it is providing. As noted above, packets break down into the types query, login, response, and cancels. Response packets are further split into multiple sub-types denoted by the first byte (a.k.a. the token) following the above header.

Note: A TDS packet that is longer than 512 bytes is split on the 512 byte boundary and the "more packets" bit is set. The full TDS packet is reassembled from its component 512 byte packets with the 8-byte headers stripped out. 512 is the block_size in the login packet, so it could be set to a different values. In Sybase you can configure a range of valid block sizes. TDS 7.0+ use a default of 4096 as block size.

TDS 4.2 & 5.0 Login Packet

Packet type (first byte) is 2. The numbers on the left are decimal offsets including the 8 byte packet header. 

byte   var type    description
------------------------------
   8   CHAR[30]    host_name
  38   INT8        host_name_length
  39   CHAR[30]    user_name
  69   INT8        user_name_length
  70   CHAR[30]    password
 100   INT8        password_length
 101   CHAR[30]    host_process
 131   INT8        host_process_length
 132   ?           magic1[6]          /* mystery stuff */
 138   INT8        bulk_copy 
 139   ?           magic2[9]          /* mystery stuff */
 148   CHAR[30]    app_name
 178   INT8        app_name_length
 179   CHAR[30]    server_name
 209   INT8        server_name_length
 210   ?           magic3[1]          /* 0, don't know this one either */
 211   INT8        password2_length
 212   CHAR[30]    password2
 242   CHAR[223]   magic4
 465   INT8        password2_length_plus2
 466   INT16       major_version      /* TDS version */
 468   INT16       minor_version      /* TDS version */
 470   CHAR        library_name[10]   /* "Ct-Library" or "DB-Library" */
 480   INT8        library_length
 481   INT16       major_version2     /* program version */
 483   INT16       minor_version2     /* program version */
 485   ?           magic6[3]          /* ? last two octets are 13 and 17 */
                                      /* bdw reports last two as 12 and 16 here  */
                                      /* possibly a bitset flag  */
 488   CHAR[30]    language           /* e.g. "us-english" */
 518   INT8        language_length
 519   ?           magic7[1]          /*  mystery stuff */
 520   INT16       old_secure         /* explanation? */
 522   INT8        encrypted          /*  1 means encrypted all password fields blank */
 523   ?           magic8[1]          /*  no clue... zeros */
 524   CHAR        sec_spare[9]       /* explanation? */
 533   CHAR[30]    char_set           /* e.g. "iso_1" */
 563   INT8        char_set_length
 564   INT8        magic9[1]          /* 1 */ 
 565   CHAR[6]     block_size         /*  in text */
 571   INT8        block_size_length 
 572   ?           magic10[25]        /* lots of stuff here...no clue */

Any help with the magic numbers would be most appreciated.

TDS 7.0+ Login Packet

byte  var type  description
---------------------------
  0   INT32	total packet size
  4   INT8[4]	TDS Version	
                	0x00000070 7.0
			0x01000071 7.1
                	0x02000972 7.2 (7.2.9?)
  8   INT32	packet size (default 4096)
 12   INT8[4]	client program version
 16   INT32	PID of client
 20   INT32	connection id (usually 0)
 24   INT8	option flags 1
                0x80 enable warning messages if SET LANGUAGE issued
                0x40 change to initial database must succeed
                0x20 enable warning messages if USE <database> issued
                0x10 enable BCP
		0x08 use ND5000 floating point format (untested)
		0x04 use VAX floating point format (untested)
		0x02 use EBCDIC encoding (untested)
		0x01 use big-endian byte order (untested)
 25   INT8	option flags 2
                0x80 enable domain login security
		0x40 "USER_SERVER - reserved" 
		0x20 user type is "DQ login"
		0x10 user type is "replication login"
		0x08 "fCacheConnect"
		0x04 "fTranBoundary"
                0x02 client is an ODBC driver
                0x01 change to initial language must succeed
 26   INT8	0x04 spawn user instance (TDS 7.2)
                0x02 XML data type instances are returned as binary XML (TDS 7.2)
                0x01 password change requested (TDS 7.2)
 27   INT8	0x01 SQL Type: 0 = use default, 1 = use T-SQL (TDS 7.2)
 28   INT8[4]	time zone (0x88ffffff ???)
 32   INT8[4]	collation information
 36   INT16	position of client hostname (86)
 38   INT16	hostname length
 40   INT16	position of username
 42   INT16	username length
 44   INT16	position of password
 46   INT16	password length
 48   INT16	position of app name
 50   INT16	app name length
 52   INT16	position of server name
 54   INT16	server name length
 56   INT16	position of remote server/password pairs
 58   INT16	remote server/password pairs length
 60   INT16	position of library name
 62   INT16	library name length
 64   INT16	position of language
 66   INT16	language name (for italian "Italiano", coded UCS2)
 68   INT16	position of database name
 70   INT16	database name length
 72   INT8[6]	MAC address of client
 78   INT16	position of auth portion
 80   INT16	NT authentication length
 82   INT16	next position (same as total packet size)
 84   INT16	0
 86   UCS2LE[n] hostname
      UCS2LE[n]	username
      UCS2LE[n]	encrypted password
      UCS2LE[n]	app name
      UCS2LE[n]	server name
      UCS2LE[n]	library name
      UCS2LE[n]	language name
      UCS2LE[n]	database name
      NT Authentication packet

NT Authentication packet
  0   CHAR[8]	authentication id "NTLMSSP\0"
  8   INT32     1  message type
 12   INT32	0xb201 flags
 16   INT16	domain length
 18   INT16     domain length
 20   INT32     domain offset
 24   INT16     hostname length
 26   INT16     hostname length
 28   INT32     hostname offset
 32   CHAR[n]   hostname
      CHAR[n]   domain
See documentation on Samba for detail (or search ntlm authentication for IIS)

For mssql 2005 before hostname (byte 86) you have
 86   INT16     next position,  or 
                position of file name for a database to be 
                attached during the connection process
 88   INT16     database filename length
 90   INT16     new password position
 92   INT16     new password length
 94   UCS2LE[n] hostname
      ... (as above)

"current pos" is the starting byte address for a Unicode string within the packet. The length of that Unicode string immediately follows. That implies there are at least 2 more strings that could be defined. (character set??)

Username and password are empty if domain authentication is used.

If the client uses an authentication packet, the server replies with an Authentication token followed by an Authentication packet.

TDS 7.0 Authentication Packet

 varies
+------+
| auth |
+------+

auth   authentication data
       for NTLM this message 3

This packet usually follows Authentication token.

Types

HEXDECtypeprotocolnullablesizecollate
0x1F31SYBVOID7+no0
0x2234SYBIMAGEyes4
0x2335SYBTEXTyes4yes
0x2436SYBUNIQUE7+yes1
0x2537SYBVARBINARYyes1
0x2638SYBINTNyes1
0x2739SYBVARCHARyes1
0x2D45SYBBINARYyes1
0x2F47SYBCHARyes1
0x3048SYBINT1no0
0x3250SYBBITno0
0x3452SYBINT2no0
0x3856SYBINT4no0
0x3A58SYBDATETIME4no0
0x3B59SYBREALno0
0x3C60SYBMONEYno0
0x3D61SYBDATETIMEno0
0x3E62SYBFLT8no0
0x4064SYBSINT15no0
0x4165SYBUINT25no0
0x4266SYBUINT45no0
0x4367SYBUINT85no0
0x6298SYBVARIANT7+yes4
0x6399SYBNTEXT7+yes4yes
0x67103SYBNVARCHAR7+yes1
0x68104SYBBITNyes1
0x6A106SYBDECIMALyes1
0x6C108SYBNUMERICyes1
0x6D109SYBFLTNyes1
0x6E110SYBMONEYNyes1
0x6F111SYBDATETIMNyes1
0x7A122SYBMONEY4no0
0x7F127SYBINT8no0
0xA5165XSYBVARBINARY7+yes2 *
0xA7167XSYBVARCHAR7+yes2 *yes
0xAD173XSYBBINARY7+yes2
0xAF175XSYBCHAR7+yes2yes
0xE1225SYBLONGBINARY5yes4
0xE7231XSYBNVARCHAR7+yes2 *yes
0xEF239XSYBNCHAR7+yes2yes

* Under TDS 7.2+ these types allow size to be -1, representing varchar(max), varbinary(max) and nvarchar(max). Data representation for them changes:

  • size is 64 (not 16) bits
  • size of -1 means NULL
  • size of -2 means the size is unknown
  • the data are split in chunks, where each chunk starts with a 32-bit size
  • a chunk with size <= 0 is the terminal chunk

Collation type - TDS 7.1

The collation structure contains information about the character set encoding and comparison method.

 INT16      INT16    INT8
+----------+--------+------------+
| codepage | flags  | charset_id |
+----------+--------+------------+

codepage    windows codepage (see http://www.microsoft.com/globaldev/nlsweb/)
            also specified in lcid column of master..syslanguages
flags       sort flags
            0x100 binary compare
            0x080 width insensitive
            0x040 Katatype insensitive
            0x020 accent insensitive
            0x010 case insensitive
            If binary flag is specified other flags are not present
            Low nibble of flags is a charset specifier (like chinese dialect)
charset_id  charset id in master..syscharsets table or zero for no SQL collations

Collations names can be obtained from select name from ::fn_helpcollations() query

Column Metadata

 INT8          XCHAR[n]       INT8    INT32   INT8
+-------------+--------------+-------+-------+---------+
| column name | column name  | flags |  user | column  |
|   length    |              |       |  type |  type   |
+-------------+--------------+-------+-------+---------+

 varies        INT8       INT8       INT16      XCHAR[n]     INT8     varies
+-------------+----------+----------+----------+------------+--------+--------+
| column size |precision |  scale   | t length | table name | locale | locale |
|             |          |          |          |            | length |  info  |
| (optional)  |(optional)|(optional)|(optional)| (optional) | (opt)  | (opt)  |
+-------------+----------+----------+----------+------------+--------+--------+

column name length 
column name        column name in result set, not necessarily db column name
flags              bit flags
                   0x1  hidden (TDS 5.0)
                   0x2  key
                   0x10 writable
                   0x20 can be NULL
                   0x40 identity
user type          usertype column from syscolumns
column type        column type
column size        not present for fixed size columns
precision          present only for SYBDECIMAL and SYBNUMERIC
scale              present only for SYBDECIMAL and SYBNUMERIC
t length           present only for SYBTEXT and SYBIMAGE, length of table name
table name         present only for SYBTEXT and SYBIMAGE
locale length      length of locale info (in bytes)
                   only for TDS 5.0 results (not for parameters)
locale info        unknown
                   only for TDS 5.0 results (not for parameters)

Client request

Normal tokens (contained in packets 0xF) 

TODO

Special packets

Language packet (0x1 1)

This sample packet contain just SQL commands. It's supported by all TDS version (although TDS 5.0 have others token with similar use) 

  XCHAR[n]
+---------+
| string  |
+---------+

string   SQL text

RPC packet (0x3 3)

Do not confuse an RPC packet with an RPC token. The RPC packet is supported by all version of TDS; the RPC token is supported only by TDS 5.0 (and has different format). This is the oldest (and the only one in mssql) way to call directly an RPC. Sybase also documents it, but as 0xE. 

  INT16         XCHAR[n]   INT16  
+-------------+----------+-------+----------+
| name length | rpc name | flags | params   |
+-------------+----------+-------+----------+

name length   length of RPC name in characters. 
              mssql2k+ support some core RPC using numbers
              If a number is used instead of name name length is marked as -1
              (null) and a INT16 is used for the name.
                0x1  1  sp_cursor
                0x2  2  sp_cursoropen
                0x3  3  sp_cursorprepare
                0x4  4  sp_cursorexecute
                0x5  5  sp_cursorprepexec
                0x6  6  sp_cursorunprepare
                0x7  7  sp_cursorfetch
                0x8  8  sp_cursoroption
                0x9  9  sp_cursorclose
                0xA  10 sp_executesql
                0xB  11 sp_prepare
                0xC  12 sp_execute ???
                0xD  13 sp_prepexec
                0xE  14 sp_prepexecrpc
                0xF  15 sp_unprepare
              sp_execute seems to have some problems, even MS ODBC use name
              version instead of number.
rpc name      name of RPC.
flags         bit flags. 
               0x1 1 recompile procedure (TDS 7.0+/TDS 5.0)
               0x2 2 no metadata (TDS 7.0+)
                     (I don't know meaning of "no metadata" -- freddy77)
params        parameters. See below

Every parameter has the following structure

+-----------+------+
| data info | data |
+-----------+------+
data info    data information. See below
data         data. See results for detail

Data info structure

  INT8          XCHAR[n]     INT8    INT32
+-------------+------------+-------+--------------------+
| name length | param name | flags | usertype (TDS 5.0) |
+-------------+------------+-------+--------------------+
  INT8   varies  varies     INT8[5]         INT8
+------+-------+----------+---------------+------------------+
| type | size  | optional | collate       | locale           |
|      | (opt) | (opt)    | info(TDS 7.1) | length (TDS 5.0) |
+------+-------+----------+---------------+------------------+

name length   parameter name length (0 if unused)
param name    parameter name
flags         bit Name           Meaning
              0x1 TDS_RPC_OUTPUT output parameter
              0x2 TDS_RPC_NODEF  output parameter has no default value. 
                                 Valid only with TDS_RPC_OUTPUT.

usertype      usertype
type          param type
size          see Results
optional      see Results. Blobs DO NOT have 
              optional on input parameters (output blob parameters
              are not supported by any version of TDS).
collate info  only for type that want collate info and using TDS 7.1
locale length locale information length. Usually 0 (if not locale
              information follow, the structure is unknown)

Chained RPCs

Under TDS 7.0+ is possible to chain multiple RPCs together. This is useful to limit packets and round-trips with server. RPCs can be chained using byte 0x80 (TDS 7.0/TDS 7.1) or 0xFF (TDS 7.2).

       INT8                     INT8
+-----+------------------------+----------------+-----+
| RPC | 0x80 (TDS 7.0/TDS 7.1) | 0xFF (TDS 7.2) | RPC | ...
+-----+------------------------+----------------+-----+

Bulk Copy packet (0x7 7)

This documents a TDS 5.0 packet. It might be true for others....

BCP Packet Structure

 INT8       INT16          INT32                
+----------+-------------+--------------------+
|  packet  | last packet |  packet            |
| type = 7 |  indicator  |   size             |
+----------+-------------+--------------------+

		followed by N row buffers, 
		where N is computed by exhausting the packet size

BCP Packet Row Buffer

 INT16          INT8       INT8	      INT16	    
+--------------+----------+----------+--------------+
| size         |  ncols   |  zero    | size (again) |
+--------------+----------+----------+--------------+

	followed by column buffers (data), where 
		
		first, the fixed-size datatype columns

		 fixed size and count (determined by column definition)
		+--------------+
		|    data .... | [repeats once for each mandatory column]
		+--------------+

		then, the variable-size (including nullable) datatype columns

		 variable size and count
		+--------------+
		|    data .... | [repeats ncol times]
		+--------------+

		followed by two tables (!) to describe the column buffers

 Adjustment Table (optional)
 
 INT8       INT8        
+----------+----------+
| 1 + ncols| offset   | [repeats ncol + 1 times]
+----------+----------+

 Offset Table (mandatory)
 
 INT8       INT8        
+----------+----------+
| 1 + ncols| offset   | [repeats ncol + 1 times]
+----------+----------+

The BCP packet has a slightly different Packet header!?

Computation of Offset and Adjustment tables

The offset and adjustment tables describe the postion of the first byte of each variable-size column. The first element holds the count of elements in the offset/adjustment table. Thereafer, the offsets are arranged in reverse order: the last element — which is also the last byte of the row buffer — holds the offset from the start of the row of the first variable-size column. The next-to-last offset table element holds the starting position of the second variable-size column, and so on.

Offset Table Example

  1. 5
  2. 31
  3. 22
  4. 21
  5. 8
  6. 4

The first element is 5 because there are five elements in the list. There are 4 column data buffers with 5 endpoints. The first column's data begins at offset 4. Computations:

column 1
offset 4
length: 4 = 8 - 4
column 2
offset 8
length: 13 = 21 - 8
column 3
offset 21
length: 1 = 22 - 21
column 4
offset 22
length: 9 = 31 - 22

Any column not accounted for is implicitly NULL. To represent a NULL column between two dataful columns, the offset table will have adjacent entries of the same value.

Adjustment table

The so-called adjustment table provides for longer rows. The reader will note the Offset table has 8-bit elements, which would limit the width of the table: the last variable column would have to end less than 256 bytes from the start fo the row. Rather than changing the definition of the Offset table, a second table, the Adjustment table, was introduced. It holds high-order bytes for the column offsets.

In other words, to compute a variable column's offset from the start of the row buffer, the server looks up its offset table value, then consults the same position in the adjustment table, and splices them together.

Offset table commentary

The BCP packet is very dense. The data formats are governed by the table definition. Non-NULL columns of course must be present; there is no need to count them or compute their size. The NULL columns are undelimited; their boundaries are defined by the minimalist offset table.

The Adjustment table seems silly at first glance. Why not just make the offset table's elements 16 or or even 32 bits? The reason is overhead. Most rows will have less than 256 bytes of variable column data. By using the adjustment table, the BCP packet avoids adding one or even three empty bytes per column per row.

Why is the table in reverse order? Because that places the first offset at a known location: the end of each row gives the start of the first column. The server can work its way down the offset table and compute the column sizes. If they don't add up — if there are data between the (presumed) end of the last column and the start of the offset table — the server knows it should look for an adjustment table. Because the scheme is infinitely repeatable, rows could one day grow to terabyte widths without redefining the packet structure.

Server Responses

Responses from the server start with a single octet (token) identifying its type. If variable length, they generally have the length as the second and third bytes

Tokens encountered thus far:
HEXDECnamenote
0x2032Param Format 25.0 only
0x2133Language5.0 only, client-side
0x2234OrderBy 25.0 only??
0x6197Row Format 25.0 only
0x71113"Logout"5.0? ct_close(), client-side?
0x79121Return Status 
0x7C124Process ID4.2 only
0x80128Cursor Close5.0 only
0x81129Cursor Delete5.0 only
0x811297.0 Result7.0 only
0x82130Cursor Fetch5.0 only
0x83131Cursor Info5.0 only
0x84132Cursor Open5.0 only
0x86134Cursor Declare5.0 only
0x881367.0 Compute Result7.0 only
0xA0160Column Name4.2 only
0xA1161Column Format4.2 only
0xA3163Dynamic 25.0 only
0xA4164Table namesname of tables in a FOR BROWSE select
0xA5165Column Infocolumn information in a FOR BROWSE select
0xA6166Option Cmd5.0 only
0xA7167Compute Names 
0xA8168Compute Result 
0xA9169Order By 
0xAA170Error Message 
0xAB171Info Message 
0xAC172Output Parameters 
0xAD173Login Acknowledgement 
0xAE174Control 
0xD1209Data --- Row Result 
0xD3211Data --- Compute Result 
0xD7215Params5.0 only
0xE2226Capability5.0 only. Information on server
0xE3227Environment Change(database change, packet size, etc...)
0xE5229Extended Error Message 
0xE6230DBRPC5.0 only RPC calls
0xE7231Dynamic5.0 only
0xEC236Param Format5.0 only
0xED237Authentication7.0 only
0xEE238Result Set5.0 only
0xFD253Result Set Done 
0xFE254Process Done 
0xFF255Done inside Process 

Param Format 2 - TDS 5.0 (0x20 32)

TODO.  

Language - TDS 5.0 (0x21 33)

 INT32    INT8     CHAR[n]
+--------+--------+-------+
| length | status | query |
+--------+--------+-------+

length  total token length
status  0 no args
        1 has args (followed by PARAMFMT/PARAMS)
query   query (total length - 1)

Order By 2 (0x22 34)

TODO.  

Row Format 2 - TDS 5.0 (0x61 97)

TODO.  

"Logout" (0x71 113)

No information. (1 byte, value=0 ?)  

Return Status (0x79 121)

 INT32
+---------------+
| Return status |
+---------------+

The return value of a stored procedure.  

Process ID (0x7C 124)

 8 bytes
+----------------+
| process number |
+----------------+

Presumably the process ID number for an executing stored procedure. (I'm not sure how this would ever be used by a client. *mjs*)  

Cursor Close - TDS 5.0 (0x80 128)

TODO.  

Cursor Delete - TDS 5.0 (0x81 129)

TODO.  

Result - TDS 7.0+ (0x81 129)

 INT16  
+----------+-------------+
| #columns | column_info | 
+----------+-------------+

The TDS 7.0 column_info is formatted as follows for each column:

 INT16      INT16   INT8   varies  varies     INT8[5]         INT8          UCS2LE[n]
+----------+-------+------+-------+----------+---------------+-------------+---------+
| usertype | flags | type | size  | optional | collate       | name length | name    | 
|          |       |      | (opt) | (opt)    | info(TDS 7.1) |             |         |
+----------+-------+------+-------+----------+---------------+-------------+---------+

usertype	type modifier
flags		bit flags
		0x1  can be NULL
		0x8  can be written (it's not an expression)
		0x10 identity 
type		data type, values >128 indicate a large type
size		none for fixed size types
		4 bytes for blob and text
		2 bytes for large types
		1 byte for all others
optional
                               INT8        INT8
                              +-----------+-------+
  numeric/decimal types:      | precision | scale |
                              +-----------+-------+

                               INT16               UCS2LE[n]
                              +-------------------+------------+
  blob/text types:            | table name length | table name |
                              +-------------------+------------+

  collate info are available only using TDS 7.1 and for characters types (but not
  for old type like short VARCHAR, only 2byte length versions)

Cursor Fetch - TDS 5.0 (0x82 130)

TODO.

Cursor Info - TDS 5.0 (0x83 131)

TODO.

Cursor Open - TDS 5.0 (0x84 132)

TODO.

Cursor Declare - TDS 5.0 (0x86 134)

TODO.

Compute Result - TDS 7.0+ (0x88 136)

TODO.

Column Name (0xA0 160)

 INT16          INT8      CHAR[n]               INT8      CHAR[n] 
+--------------+---------+--------------+------+---------+--------------+
| total length | length1 | column1 name | .... | lengthN | columnN name |
+--------------+---------+--------------+------+---------+--------------+

This token is the first token that contain result informations. Is usually followed by Column Format token (0xA1 161)

Column Format (0xA1 161)

 INT16  
+--------------+-------------+
| total length | column_info | 
+--------------+-------------+

The number of columns is the same of previous Column Name token.

The TDS 4.2 column_info is formatted as follows for each column: 

 INT8[4]     INT8   varies  varies
+-----------+------+-------+----------+
| usertype/ | type | size  | optional |
|   flags   |      | (opt) | (opt)    |
+-----------+------+-------+----------+

usertype/flags for Sybase

   INT32
  +----------+
  | usertype |
  +----------+

usertype/flags for MSSQL

   INT16
  +----------+-------+
  | usertype | flags |
  +----------+-------+

usertype	type modifier
flags		bit flags (only MSSQL)
		0x1  can be NULL
		0x8  can be written (it's not an expression)
		0x10 identity 
type		data type
size		none for fixed size types
		4 bytes for blob and text
		1 byte for all others
                (TDS 4.2 do not support large types)
optional
                               INT8        INT8
                              +-----------+-------+
  numeric/decimal types:      | precision | scale |
  (supported??)               +-----------+-------+

                               INT16               CHAR[n]
                              +-------------------+------------+
  blob/text types:            | table name length | table name |
                              +-------------------+------------+

Dynamic 2 - TDS 5.0 (0xA3 163)

TODO.

Option Cmd - TDS 5.0 (0xA6 166)

TODO.

Compute Result (0xA8 168)

 INT16          INT16        INT8       varies        INT8      INT8[n]
+--------------+------------+----------+-------------+---------+-------+
| total length | compute id | #columns | column info | #bycols | bycol |
+--------------+------------+----------+-------------+---------+-------+

column info:

 INT8       INT8      INT32      INT8     varies  INT8               varies
+----------+---------+----------+--------+-------+------------------+----------------+
| operator | operand | usertype | column | size  | locale length    | locale info    |
|          |         |          |  type  | (opt) |  info (TDS 5.0)  | (TDS 5.0)      |
+----------+---------+----------+--------+-------+------------------+----------------+

operator      operator
              0x4b COUNT
              0x4c UNSIGNED? COUNT
              0x4d SUM
              0x4e UNSIGNED? SUM
              0x4f AVG
              0x50 UNSIGNED? AVG
              0x51 MIN
              0x52 MAX
              0x09 COUNT_BIG (mssql2k)
              0x30 STDEV (mssql2k)
              0x31 STDEVP (mssql2k)
              0x32 VAR (mssql2k)
              0x33 VARP (mssql2k)
              0x72 CHECKSUM_AGG (mssql2k)
operand       ???
usertype      usertype
column type   data type
size          data size
locale length length of locale informations
locale info   locale informations (unknown)

Each bycol information contains column info for a specific column.

TODO: optional possible?? collate infos ??

TabName (0xA4 164)

TDS4/5/7:

 INT16          INT16         XCHAR[n]
+--------------+-------------+------------+
| total length | name length | table name | ...
+--------------+-------------+------------+

name length   table name length
table name    table name

TDS 7.1:

 INT16          varies
+--------------+-------------+
| total length | table names |
+--------------+-------------+

table name:
 INT8              INT16              XCHAR[n]
+-----------------+------------------+----------------+
| # of components | component length | component name |
+-----------------+------------------+----------------+

ie:
  name        -> 01  04 00  ucs2le "name"
  db..name    -> 03  02 00  ucs2le "db"  00 00  04 00  ucs2le "name"
  db.dbo.name -> 03  02 00  ucs2le "db"  03 00  ucs2le "dbo"  04 00  ucs2le "name"

Column Info (0xA5 165)

 INT16          varies
+--------------+--------------+
| total length | column infos |
+--------------+--------------+

column info:

 INT8    INT8          INT8    INT8          XCHAR[n]
+-------+-------------+-------+-------------+-------------+
| index | table index | flags | name length | column name |
|       |             |       |  (opt)      |  (opt)      |
+-------+-------------+-------+-------------+-------------+

index        index in result format (1-based)
table index  index in previous TabName (1-based)
             0 means no table (ie computed)
flags        set of flags
             0x04 expression
             0x08 key
             0x10 hidden
             0x20 column name present
name length  length of following column
column name  real column name (result contain the label)

This token follow TabName token    

compute "control" ? (0xA7 167)

"control" (0xAE 174)

Miscellaneous note (from *bdw* ?) found with 0xAE: 

  has one byte for each column, 
  comes between result(238) and first row(209),
  I believe computed column info is stored here, need to investigate

Order By (0xA9 169)

 INT16    variable (1 byte per col)
+--------+---------+
| length | orders  |
+--------+---------+

length		Length of packet(and number of cols)
orders          one byte per order by indicating the
                column # in the output matching the
                order from Column Info and Column Names
                and data in following Row Data items.
                A 0 indicates the column is not in the
                resulting rows.

an example:
select first_name, last_name, number from employee
order by salary, number
assuming the columns are returned in the order
queried:
first_name then last_name, then number. we would have:
----------------
|  2   | 0 | 3 |
----------------
where length = 2 then the orders evaluate:
0 for salary, meaning there is no salary data returned
3 for number, meaning the 3rd data item corresponding
to a column is the number

 

Error Message (0xAA 170)

Non-error Message (0xAB 171)

Extended Error Message (0xE5 229)

 INT16    INT32        INT8    INT8    
+--------+------------+-------+-------+
| length | msg number | state | level |
+--------+------------+-------+-------+

 INT16      XCHAR[n]  INT8       XCHAR[n]  INT8       XCHAR[n]  INT16             INT32
+----------+---------+----------+---------+----------+---------+-----------------+-----------------+
| m length | message | s length | server  | p length | process | line#(TDS 7.1-) | line# (TDS 7.2) |
+----------+---------+----------+---------+----------+---------+-----------------+-----------------+

length		Length of packet
msg number	SQL message number
state		?
level		An error if level > 10, a message if level <= 10
m length	Length of message
message		Text of error/message
s length	Length of server name
server		Name of "server" ?
p length	Length of process name
process name	Stored procedure name, if any
line#		Line number of input which generated the message

Output Parameters (0xAC 172)

  Output parameters of a stored procedure. 

 INT16    INT8       XCHAR[n]  INT8    INT32      INT8
+--------+----------+---------+-------+----------+----------+------+
| length | c length | colname | flags | usertype | datatype | .... | 
+--------+----------+---------+-------+----------+----------+------+

length		Length of packet
c length	Length of colname
colname		Name of column
flags		0x1 Nullable
usertype	cf. systypes table in database
datatype	Type of data returned

The trailing information depends on whether the datatype is
a fixed size datatype.
				 N bytes
				+---------+
  Datatype of fixed size N	| data    |
				+---------+

				 INT8          INT8            N bytes
				+-------------+---------------+--------+
  Otherwise			| column size | actual size N | data   |
				+-------------+---------------+--------+

Login Acknowledgement (0xAD 173)

 INT16    INT8    4 bytes   INT8       XCHAR[n] 4 bytes
+--------+-------+---------+----------+--------+----------+
| length |  ack  | version | t length |  text  | ser_ver  |
+--------+-------+---------+----------+--------+----------+

length		length of packet
ack		0x01 success	4.2
		0x05 success	5.0
		0x06 failure	5.0
version		TDS version 4 bytes:  major.minor.?.?
t length	length of text
text		server name (ie 'Microsoft SQL Server')
ser_ver		Server version
		(with strange encoding, differring from TDS version)

   

Data - Row Result (0xD1 209)

Data - Compute Result (0xD3 211)

 INT8       variable size
+----------+--------------------+
|  token   |   row data         |
+----------+--------------------+

Row data starts with one byte (decimal 209), for variable length types, a one byte length field precedes the data, for fixed length records just the data appears.
Note: nullable integers and floats are variable length.

For example: sp_who

The first field is spid, a smallint
The second field is status a char(12), in our example "recv sleep "

The row would look like this: 

  byte  0 is the token
  bytes 1-2 are a smallint in low-endian
  byte  3 is the length of the char field
  bytes 4-15 is the char field

byte  0   1   2   3   4   5   6   7   8   9  10  11  12  13  14  15
hex  D1  01  00  0C  72  65  63  76  20  73  6C  65  65  70  20  20
    209   1   0  12   r   e   c   v ' '   s   l   e   e   p ' ' ' '

Params - TDS 5.0 (0xD7 215)

TODO.

Capability - TDS 5.0 (0xE2 226)

 INT16    variable
+--------+--------------+
| length | capabilities |
+--------+--------------+

length		Length of capability string
capabilities	Server capabilities?  Related to login magic?

Environment change (0xE3 227)

 INT16    INT8       INT8        CHAR[n]   INT8        CHAR[n] 
+--------+----------+-----------+---------+-----------+---------+
| length | env code | t1 length |  text1  | t2 length |  text2  |
+--------+----------+-----------+---------+-----------+---------+

env code	Code for what part of environment changed
	0x01  database context
	0x02  language
	0x03  character set
	0x04  packet size
	0x05  TDS 7.0+ LCID
	0x06  TDS 7.0+ ??? (sort method? sql server encoding?)
	0x07  Collation info
text1		Old value
text2		New value

text1 and text2 are text information (coded in ucs2 in TDS 7.0+) except 
collation info that's a structure (see collation structure)

DBRPC - TDS 5.0 (0xE6 230)

TODO.

Dynamic - TDS 5.0 (0xE7 231)

TODO.

Param Format - TDS 5.0 (0xEC 236)

 INT16     INT16        variable size
+---------+------------+-------------------+
| length  | number of  | parameter info    |
|         | parameters |                   |
+---------+------------+-------------------+

length            	length of message following this field
number of parameters	number of parameter formats following
list of formats		I (*bdw*) imagine it uses the column format structure.

Authentication - TDS 7.0 (0xED 237)

 INT16     varies
+---------+------+
| length  | auth |
+---------+------+

length   length of authentication data following this field
auth     authentication data
         for NTLM this is message 2

Client reply with Authentication packet.

Result Set - TDS 5.0 (0xEE 238)

 INT16     INT16        variable size
+---------+------------+-----------------+
| length  | number of  | column info     |
|         | columns    |                 |
+---------+------------+-----------------+


Fields:
length             length of message following this field
number of columns  number of columns in the result set, this many column
                   information fields will follow.
column info        column info

Done Packets

Result Set Done (0xFD 253)
Process Done (0xFE 254)
Done Inside Process (0xFF 255)

 INT16       INT16     INT32                  INT64
+-----------+---------+----------------------+---------------------+
| bit flags | unknown | row count (TDS 7.1-) | row count (TDS 7.2) |
+-----------+---------+----------------------+---------------------+

Fields:
bit flags          0x01 more results
		   0x02 error (like invalid sql syntax)
		   0x10 row count is valid
		   0x20 cancelled
unknown            2,0  /* something to do with block size perhaps */
row count          number of rows affected / returned in the result set. 
                   row count is 64-bit using TDS 7.2.
		(FIXME check if "affected / returned" is correct)

"Result Set Complete" is the end of a query that doesn't create a process on the server. I.e., it doesn't call a stored procedure.
"Process Done" is the end of a stored procedure
"Done In Process" means that a query internal to a stored procedure has finished, but the stored procedure isn't done overall.

Acknowledgements

The following people have contributed to this document:

  • Brian Bruns (first draft, protocol discovery)
  • Brian Wheeler (protocol discovery)
  • Mark Schaal (second draft)
  • Frediano Ziglio

(short list)

Document Status

$Id: tds.html,v 1.41 2008-11-25 23:38:33 jklowden Exp $

Valid HTML 4.01 Strict

doc/freetds/ea-freetds-1.4.9/README.md000064400000006016147633065420012727 0ustar00README for FreeTDS 1.4 ==== *Release date 23th September 2023* **To build FreeTDS read the file [INSTALL](./INSTALL.md) or the [FreeTDS Users Guide](http://www.freetds.org/userguide/)** FreeTDS is a free implementation of Sybase's DB-Library, CT-Library, and ODBC libraries. FreeTDS builds and runs on every flavor of unix-like systems we've heard of (and some we haven't) as well as Win32 (with or without Cygwin), VMS, and Mac OS X. Failure to build on your system is probably considered a bug. It has C language bindings, and works also with Perl and PHP, among others. FreeTDS is licensed under the GNU LGPL license. See [COPYING_LIB.txt](./COPYING_LIB.txt) for details. Other files you might want to peruse: * [AUTHORS](./AUTHORS.md) Who's involved * [NEWS](./NEWS.md) Summary of feature changes and fixes * [TODO](./TODO.md) The roadmap, such as it is Also, [api_status](./doc/api_status.txt) shows which functions are implemented. For details on what's new in this version, see NEWS. For unbearable detail, see git log. Documentation ============= A User Guide, in XML and HTML form, is included in this distribution. Also included is a reference manual, generated in HTML with Doxygen. "make install" installs the HTML documentation, by default to /usr/local/share/doc/freetds-. Note to Users ============= Submissions of test programs (self-contained programs that demonstrate functionality or problems) are greatly appreciated. They should create any tables needed (since we obviously don't have access to your database) and populate them. Unit tests for any of the libraries is appreciated Notes to Developers =================== The code is split into several pieces. 1. `tds` directory is the wire level stuff, it should be independent of the library using it, this will allow db-lib, ct-lib, and ODBC to sit on top. 2. `db-lib` directory. This is the actual db-lib code which runs on top of tds. 3. `ct-lib` directory. This is the ct-lib code which runs on top of tds. 4. `server` directory. This will be a set of server routines basically to impersonate a dataserver, functions like send_login_ack() etc... 5. `odbc` directory. ODBC implementation over tds. Uses iODBC or unixODBC as a driver manager. You need to have one of those if you are using the ODBC CLI. 6. `unittests` directories. Test harness code for ct-lib, db-lib, ODBC and libtds. 7. `samples` directories. Sample code for getting started with Perl, PHP, etc... 8. `pool` directory. A connection pooling server for TDS. Useful if you have a connection limited license. Needs some hacking to get configured but is quite stable once configured correctly. Contact the list if interested in how to use it. Please look at doc/getting_started.txt for a description of what is going on in the code. Side note: Brian, as many free software authors, appreciates postcards from all over. So if you live someplace neat (read: not Michigan) and want to send one, email him (brian@bruns.org) for his current snail mail address. doc/freetds/ea-freetds-1.4.9/COPYING.txt000064400000043254147633065420013326 0ustar00 GNU GENERAL PUBLIC LICENSE Version 2, June 1991 Copyright (C) 1989, 1991 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. Preamble The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Lesser General Public License instead.) You can apply it to your programs, too. When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things. To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it. For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights. We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software. Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations. Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all. The precise terms and conditions for copying, distribution and modification follow. GNU GENERAL PUBLIC LICENSE TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 0. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term "modification".) Each licensee is addressed as "you". Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does. 1. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program. You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee. 2. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions: a) You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change. b) You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License. c) If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.) These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it. Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program. In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License. 3. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following: a) Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or, b) Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or, c) Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.) The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable. If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code. 4. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. 5. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it. 6. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License. 7. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program. If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances. It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice. This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License. 8. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License. 9. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation. 10. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally. NO WARRANTY 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. END OF TERMS AND CONDITIONS How to Apply These Terms to Your New Programs If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms. To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found. Copyright (C) This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Also add information on how to contact you by electronic and paper mail. If the program is interactive, make it output a short notice like this when it starts in an interactive mode: Gnomovision version 69, Copyright (C) year name of author Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. This is free software, and you are welcome to redistribute it under certain conditions; type `show c' for details. The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than `show w' and `show c'; they could even be mouse-clicks or menu items--whatever suits your program. You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the program, if necessary. Here is a sample; alter the names: Yoyodyne, Inc., hereby disclaims all copyright interest in the program `Gnomovision' (which makes passes at compilers) written by James Hacker. , 1 April 1989 Ty Coon, President of Vice This General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Lesser General Public License instead of this License. doc/freetds/ea-freetds-1.4.9/AUTHORS.md000064400000005324147633065420013120 0ustar00Brian Bruns Started this crazy thing James K. Lowden Documentation, maintainer from 2003 to early 2015. Marc Abramowitz Testing and patches, Travis CI tests. Koscheev Andrey Negative money patch. Craig A. Berry VMS support. James Cameron GNU standards compliance and minor fixes. Peter Deacon Lots of help, testing and patches. John F. Dumas Patch to fix memory leaks. David Fraser Testing and patches (NO-DM support). Scott Gray TDS 7.0 numeric support and bug fixes. Alex Hornby Testing and patches. Mihai Ibanescu GNUified the packet. Gregg Jensen Message handlers and extra datatype support and some sybperl stuff? Viktar Klimkovitch ODBC fixes to get libodbc++ working. Bob Kline NTEXT support. Lothar Krauss ODBC fixes. Steve Langasek Off by one fixes and autoconf byte size thing. Debian package maintainer. Mark J. Lilback Implementation of dbstrlen and dbstrcpy. Kevin Lyons Various TDS bug fixes. Steve Murphree Contributed a huge ODBC patch. Dennis Nicklaus vxWorks port and fixes for dbdata() and SYBVARBINARY. Arno Pedusaar Donated his TDS4.2 code to the cause. Brandon M. Reynolds Fix for arbitrarily large queries under dblib. Thomas Rogers Testing and patches. Mark Schaal Cleaned up message handling, bug fixes, ctlib unittests. Ken Seymour ODBC Driver Fixes. Craig Spannring JDBC driver and CVS repository. Martin Spott Testing and patches. Sam Tetherow Various TDS bug fixes. Bill Thompson BCP patches and datetime fixes. Patrick van Kleef Various bug fixes, dbcanquery() and odbc version checks. Geoff Winkless Lost connection stuff. Nicholas S. Castellano Many bug fixes and improvements, contributor of fisql application. Frediano Ziglio Lot of contributions, maintainer since 2015. Special thanks to Michael Peppler , author of the DBD::Sybase Perl module. Thanks go to the folks at A2i, Inc. (http://www.a2i.com) for funding the development of dblib host file bulk copy and writetext support, and to Dave Poyourow there for helping with the debugging. doc/freetds/ea-freetds-libs-1.4.9/samples-odbc/odbctest.php000064400000001050147633065420017261 0ustar00 doc/freetds/ea-freetds-libs-1.4.9/samples-odbc/unixodbc.freetds.driver.template000064400000002067147633065420023247 0ustar00# # $Id: unixodbc.freetds.driver.template.in,v 1.2 2006-09-13 11:56:37 freddy77 Exp $ # # FreeTDS - Library of routines accessing Sybase and Microsoft databases # Copyright (C) 1998-1999 Brian Bruns # # This library is free software; you can redistribute it and/or # modify it under the terms of the GNU Library General Public # License as published by the Free Software Foundation; either # version 2 of the License, or (at your option) any later version. # # This library is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU # Library General Public License for more details. # # You should have received a copy of the GNU Library General Public # License along with this library; if not, write to the # Free Software Foundation, Inc., 59 Temple Place - Suite 330, # Boston, MA 02111-1307, USA. # [FreeTDS] Description = FreeTDS unixODBC Driver Driver = /opt/cpanel/freetds/lib64/libtdsodbc.so Setup = /opt/cpanel/freetds/lib64/libtdsodbc.so doc/freetds/ea-freetds-libs-1.4.9/samples-odbc/odbctest.pl000064400000001020147633065420017102 0ustar00#!/usr/local/bin/perl # $Id: odbctest.pl,v 1.2 2005-04-04 22:05:33 jklowden Exp $ use DBI; my ($dsn, $user, $pass, $sql) = @ARGV; $dsn = "dbi:ODBC:JDBC" unless $dsn; $user = 'guest' unless $user; $pass = 'sybase' unless $pass; $sql ="select \@\@servername" unless $sql; my $dbh = DBI->connect($dsn, $user, $pass, {PrintError => 1}); die "Unable for connect to server $DBI::errstr" unless $dbh; my $rc; my $sth = $dbh->prepare($sql); if($sth->execute) { while(@dat = $sth->fetchrow) { print "@dat\n"; } } doc/freetds/ea-freetds-libs-1.4.9/samples-odbc/unixodbc.install.sh000075500000002607147633065420020571 0ustar00#! /bin/sh # # $Id: unixodbc.install.sh,v 1.1 2002-10-09 17:05:44 castellano Exp $ # # FreeTDS - Library of routines accessing Sybase and Microsoft databases # Copyright (C) 1998-1999 Brian Bruns # # This library is free software; you can redistribute it and/or # modify it under the terms of the GNU Library General Public # License as published by the Free Software Foundation; either # version 2 of the License, or (at your option) any later version. # # This library is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU # Library General Public License for more details. # # You should have received a copy of the GNU Library General Public # License along with this library; if not, write to the # Free Software Foundation, Inc., 59 Temple Place - Suite 330, # Boston, MA 02111-1307, USA. # # Run this script as root to install FreeTDS unixODBC drivers and datasources. # # You will most likely want to edit unixodbc.jdbc.datasource.template # to add your own dataserver instead of the public Sybase dataserver. # # For more information about these template files, please see # http://www.unixodbc.org/doc/FreeTDS.html # # Install driver. odbcinst -i -d -f unixodbc.freetds.driver.template # Install system datasource. odbcinst -i -s -l -f unixodbc.jdbc.datasource.template doc/freetds/ea-freetds-libs-1.4.9/samples-odbc/odbc.ini000064400000000460147633065420016355 0ustar00; ; odbc.ini ; [ODBC Data Sources] JDBC = Sybase JDBC Server [JDBC] Driver = /usr/local/lib/libtdsodbc.so Description = Sybase JDBC Server Trace = No Servername = JDBC Database = pubs2 UID = guest [Default] Driver = /usr/local/lib/libtdsodbc.so doc/freetds/ea-freetds-libs-1.4.9/samples-odbc/unixodbc.jdbc.datasource.template000064400000002031147633065420023343 0ustar00# # $Id: unixodbc.jdbc.datasource.template,v 1.1 2002-10-09 17:05:44 castellano Exp $ # # FreeTDS - Library of routines accessing Sybase and Microsoft databases # Copyright (C) 1998-1999 Brian Bruns # # This library is free software; you can redistribute it and/or # modify it under the terms of the GNU Library General Public # License as published by the Free Software Foundation; either # version 2 of the License, or (at your option) any later version. # # This library is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU # Library General Public License for more details. # # You should have received a copy of the GNU Library General Public # License along with this library; if not, write to the # Free Software Foundation, Inc., 59 Temple Place - Suite 330, # Boston, MA 02111-1307, USA. # [JDBC] Driver = FreeTDS Description = Sybase JDBC Server Trace = No Servername = JDBC Database = pubs2 UID = guest doc/freetds/ea-freetds-libs-1.4.9/COPYING_LIB.txt000064400000061447147633065420014747 0ustar00 GNU LIBRARY GENERAL PUBLIC LICENSE Version 2, June 1991 Copyright (C) 1991 Free Software Foundation, Inc. 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. [This is the first released version of the library GPL. It is numbered 2 because it goes with version 2 of the ordinary GPL.] Preamble The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public Licenses are intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This license, the Library General Public License, applies to some specially designated Free Software Foundation software, and to any other libraries whose authors decide to use it. You can use it for your libraries, too. When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things. To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the library, or if you modify it. For example, if you distribute copies of the library, whether gratis or for a fee, you must give the recipients all the rights that we gave you. You must make sure that they, too, receive or can get the source code. If you link a program with the library, you must provide complete object files to the recipients so that they can relink them with the library, after making changes to the library and recompiling it. And you must show them these terms so they know their rights. Our method of protecting your rights has two steps: (1) copyright the library, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the library. Also, for each distributor's protection, we want to make certain that everyone understands that there is no warranty for this free library. If the library is modified by someone else and passed on, we want its recipients to know that what they have is not the original version, so that any problems introduced by others will not reflect on the original authors' reputations. Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that companies distributing free software will individually obtain patent licenses, thus in effect transforming the program into proprietary software. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all. Most GNU software, including some libraries, is covered by the ordinary GNU General Public License, which was designed for utility programs. This license, the GNU Library General Public License, applies to certain designated libraries. This license is quite different from the ordinary one; be sure to read it in full, and don't assume that anything in it is the same as in the ordinary license. The reason we have a separate public license for some libraries is that they blur the distinction we usually make between modifying or adding to a program and simply using it. Linking a program with a library, without changing the library, is in some sense simply using the library, and is analogous to running a utility program or application program. However, in a textual and legal sense, the linked executable is a combined work, a derivative of the original library, and the ordinary General Public License treats it as such. Because of this blurred distinction, using the ordinary General Public License for libraries did not effectively promote software sharing, because most developers did not use the libraries. We concluded that weaker conditions might promote sharing better. However, unrestricted linking of non-free programs would deprive the users of those programs of all benefit from the free status of the libraries themselves. This Library General Public License is intended to permit developers of non-free programs to use free libraries, while preserving your freedom as a user of such programs to change the free libraries that are incorporated in them. (We have not seen how to achieve this as regards changes in header files, but we have achieved it as regards changes in the actual functions of the Library.) The hope is that this will lead to faster development of free libraries. The precise terms and conditions for copying, distribution and modification follow. Pay close attention to the difference between a "work based on the library" and a "work that uses the library". The former contains code derived from the library, while the latter only works together with the library. Note that it is possible for a library to be covered by the ordinary General Public License rather than by this special one. GNU LIBRARY GENERAL PUBLIC LICENSE TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 0. This License Agreement applies to any software library which contains a notice placed by the copyright holder or other authorized party saying it may be distributed under the terms of this Library General Public License (also called "this License"). Each licensee is addressed as "you". A "library" means a collection of software functions and/or data prepared so as to be conveniently linked with application programs (which use some of those functions and data) to form executables. The "Library", below, refers to any such software library or work which has been distributed under these terms. A "work based on the Library" means either the Library or any derivative work under copyright law: that is to say, a work containing the Library or a portion of it, either verbatim or with modifications and/or translated straightforwardly into another language. (Hereinafter, translation is included without limitation in the term "modification".) "Source code" for a work means the preferred form of the work for making modifications to it. For a library, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the library. Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running a program using the Library is not restricted, and output from such a program is covered only if its contents constitute a work based on the Library (independent of the use of the Library in a tool for writing it). Whether that is true depends on what the Library does and what the program that uses the Library does. 1. You may copy and distribute verbatim copies of the Library's complete source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and distribute a copy of this License along with the Library. You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee. 2. You may modify your copy or copies of the Library or any portion of it, thus forming a work based on the Library, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions: a) The modified work must itself be a software library. b) You must cause the files modified to carry prominent notices stating that you changed the files and the date of any change. c) You must cause the whole of the work to be licensed at no charge to all third parties under the terms of this License. d) If a facility in the modified Library refers to a function or a table of data to be supplied by an application program that uses the facility, other than as an argument passed when the facility is invoked, then you must make a good faith effort to ensure that, in the event an application does not supply such function or table, the facility still operates, and performs whatever part of its purpose remains meaningful. (For example, a function in a library to compute square roots has a purpose that is entirely well-defined independent of the application. Therefore, Subsection 2d requires that any application-supplied function or table used by this function must be optional: if the application does not supply it, the square root function must still compute square roots.) These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Library, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Library, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it. Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Library. In addition, mere aggregation of another work not based on the Library with the Library (or with a work based on the Library) on a volume of a storage or distribution medium does not bring the other work under the scope of this License. 3. You may opt to apply the terms of the ordinary GNU General Public License instead of this License to a given copy of the Library. To do this, you must alter all the notices that refer to this License, so that they refer to the ordinary GNU General Public License, version 2, instead of to this License. (If a newer version than version 2 of the ordinary GNU General Public License has appeared, then you can specify that version instead if you wish.) Do not make any other change in these notices. Once this change is made in a given copy, it is irreversible for that copy, so the ordinary GNU General Public License applies to all subsequent copies and derivative works made from that copy. This option is useful when you wish to copy part of the code of the Library into a program that is not a library. 4. You may copy and distribute the Library (or a portion or derivative of it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange. If distribution of object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place satisfies the requirement to distribute the source code, even though third parties are not compelled to copy the source along with the object code. 5. A program that contains no derivative of any portion of the Library, but is designed to work with the Library by being compiled or linked with it, is called a "work that uses the Library". Such a work, in isolation, is not a derivative work of the Library, and therefore falls outside the scope of this License. However, linking a "work that uses the Library" with the Library creates an executable that is a derivative of the Library (because it contains portions of the Library), rather than a "work that uses the library". The executable is therefore covered by this License. Section 6 states terms for distribution of such executables. When a "work that uses the Library" uses material from a header file that is part of the Library, the object code for the work may be a derivative work of the Library even though the source code is not. Whether this is true is especially significant if the work can be linked without the Library, or if the work is itself a library. The threshold for this to be true is not precisely defined by law. If such an object file uses only numerical parameters, data structure layouts and accessors, and small macros and small inline functions (ten lines or less in length), then the use of the object file is unrestricted, regardless of whether it is legally a derivative work. (Executables containing this object code plus portions of the Library will still fall under Section 6.) Otherwise, if the work is a derivative of the Library, you may distribute the object code for the work under the terms of Section 6. Any executables containing that work also fall under Section 6, whether or not they are linked directly with the Library itself. 6. As an exception to the Sections above, you may also compile or link a "work that uses the Library" with the Library to produce a work containing portions of the Library, and distribute that work under terms of your choice, provided that the terms permit modification of the work for the customer's own use and reverse engineering for debugging such modifications. You must give prominent notice with each copy of the work that the Library is used in it and that the Library and its use are covered by this License. You must supply a copy of this License. If the work during execution displays copyright notices, you must include the copyright notice for the Library among them, as well as a reference directing the user to the copy of this License. Also, you must do one of these things: a) Accompany the work with the complete corresponding machine-readable source code for the Library including whatever changes were used in the work (which must be distributed under Sections 1 and 2 above); and, if the work is an executable linked with the Library, with the complete machine-readable "work that uses the Library", as object code and/or source code, so that the user can modify the Library and then relink to produce a modified executable containing the modified Library. (It is understood that the user who changes the contents of definitions files in the Library will not necessarily be able to recompile the application to use the modified definitions.) b) Accompany the work with a written offer, valid for at least three years, to give the same user the materials specified in Subsection 6a, above, for a charge no more than the cost of performing this distribution. c) If distribution of the work is made by offering access to copy from a designated place, offer equivalent access to copy the above specified materials from the same place. d) Verify that the user has already received a copy of these materials or that you have already sent this user a copy. For an executable, the required form of the "work that uses the Library" must include any data and utility programs needed for reproducing the executable from it. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable. It may happen that this requirement contradicts the license restrictions of other proprietary libraries that do not normally accompany the operating system. Such a contradiction means you cannot use both them and the Library together in an executable that you distribute. 7. You may place library facilities that are a work based on the Library side-by-side in a single library together with other library facilities not covered by this License, and distribute such a combined library, provided that the separate distribution of the work based on the Library and of the other library facilities is otherwise permitted, and provided that you do these two things: a) Accompany the combined library with a copy of the same work based on the Library, uncombined with any other library facilities. This must be distributed under the terms of the Sections above. b) Give prominent notice with the combined library of the fact that part of it is a work based on the Library, and explaining where to find the accompanying uncombined form of the same work. 8. You may not copy, modify, sublicense, link with, or distribute the Library except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, link with, or distribute the Library is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. 9. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Library or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Library (or any work based on the Library), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Library or works based on it. 10. Each time you redistribute the Library (or any work based on the Library), the recipient automatically receives a license from the original licensor to copy, distribute, link with or modify the Library subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License. 11. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Library at all. For example, if a patent license would not permit royalty-free redistribution of the Library by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Library. If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply, and the section as a whole is intended to apply in other circumstances. It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice. This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License. 12. If the distribution and/or use of the Library is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Library under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License. 13. The Free Software Foundation may publish revised and/or new versions of the Library General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. Each version is given a distinguishing version number. If the Library specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Library does not specify a license version number, you may choose any version ever published by the Free Software Foundation. 14. If you wish to incorporate parts of the Library into other free programs whose distribution conditions are incompatible with these, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally. NO WARRANTY 15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. END OF TERMS AND CONDITIONS How to Apply These Terms to Your New Libraries If you develop a new library, and you want it to be of the greatest possible use to the public, we recommend making it free software that everyone can redistribute and change. You can do so by permitting redistribution under these terms (or, alternatively, under the terms of the ordinary General Public License). To apply these terms, attach the following notices to the library. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found. Copyright (C) This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details. You should have received a copy of the GNU Library General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA Also add information on how to contact you by electronic and paper mail. You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the library, if necessary. Here is a sample; alter the names: Yoyodyne, Inc., hereby disclaims all copyright interest in the library `Frob' (a library for tweaking knobs) written by James Random Hacker. , 1 April 1990 Ty Coon, President of Vice That's all there is to it! doc/freetds/images/caution.gif000064400000002017147633065420012355 0ustar00GIF87a!!11BBZZcckkss{{sss{s{cZcc19B191,uH_@Ȑ 6DHB $N$ 4>pиa (e|QGE(YaD`P 8j,XEJt@P?MeHL)%d)؝ JCgep`-[ tYb 16|o "ؕd=H)UDFW4  热-XċBݐ'ơ:o ;doc/freetds/images/callouts/3.gif000064400000001632147633065420012705 0ustar00GIF89a   !!!"""###$$$%%%&&&'''((()))***+++,,,---...///000111222333444555666777888999:::;;;<<<===>>>???@@@AAABBBCCCDDDEEEFFFGGGHHHIIIJJJKKKLLLMMMNNNOOOPPPQQQRRRSSSTTTUUUVVVWWWXXXYYYZZZ[[[\\\]]]^^^___```aaabbbcccdddeeefffggghhhiiijjjkkklllmmmnnnooopppqqqrrrssstttuuuvvvwwwxxxyyyzzz{{{|||}}}~~~!, wG)98\ r@ ƹ!x0֌d.SAq$VDPsd1TBlE$gfe.FwV޽Vc,<M C҄;doc/freetds/images/callouts/8.gif000064400000001633147633065420012713 0ustar00GIF89a   !!!"""###$$$%%%&&&'''((()))***+++,,,---...///000111222333444555666777888999:::;;;<<<===>>>???@@@AAABBBCCCDDDEEEFFFGGGHHHIIIJJJKKKLLLMMMNNNOOOPPPQQQRRRSSSTTTUUUVVVWWWXXXYYYZZZ[[[\\\]]]^^^___```aaabbbcccdddeeefffggghhhiiijjjkkklllmmmnnnooopppqqqrrrssstttuuuvvvwwwxxxyyyzzz{{{|||}}}~~~!, x l%%E) |!8'PRެ ƽRxnCJ 108P\F%.s,aA9B'YD@;J8=c8sfw R";doc/freetds/images/callouts/2.gif000064400000001623147633065420012704 0ustar00GIF89a   !!!"""###$$$%%%&&&'''((()))***+++,,,---...///000111222333444555666777888999:::;;;<<<===>>>???@@@AAABBBCCCDDDEEEFFFGGGHHHIIIJJJKKKLLLMMMNNNOOOPPPQQQRRRSSSTTTUUUVVVWWWXXXYYYZZZ[[[\\\]]]^^^___```aaabbbcccdddeeefffggghhhiiijjjkkklllmmmnnnooopppqqqrrrssstttuuuvvvwwwxxxyyyzzz{{{|||}}}~~~!, pG)98\ R!{g A,e @=hDo("HfTrN+YsYS$5Ĉ!彇I=dà5- #gJ ;doc/freetds/images/callouts/10.gif000064400000001646147633065420012770 0ustar00GIF89a   !!!"""###$$$%%%&&&'''((()))***+++,,,---...///000111222333444555666777888999:::;;;<<<===>>>???@@@AAABBBCCCDDDEEEFFFGGGHHHIIIJJJKKKLLLMMMNNNOOOPPPQQQRRRSSSTTTUUUVVVWWWXXXYYYZZZ[[[\\\]]]^^^___```aaabbbcccdddeeefffggghhhiiijjjkkklllmmmnnnooopppqqqrrrssstttuuuvvvwwwxxxyyyzzz{{{|||}}}~~~!,   . ÛjJ9)) ZxHIDg_7s|3P.urF@b5<ڋ^0Up\F ;doc/freetds/images/callouts/5.gif000064400000001627147633065420012713 0ustar00GIF89a   !!!"""###$$$%%%&&&'''((()))***+++,,,---...///000111222333444555666777888999:::;;;<<<===>>>???@@@AAABBBCCCDDDEEEFFFGGGHHHIIIJJJKKKLLLMMMNNNOOOPPPQQQRRRSSSTTTUUUVVVWWWXXXYYYZZZ[[[\\\]]]^^^___```aaabbbcccdddeeefffggghhhiiijjjkkklllmmmnnnooopppqqqrrrssstttuuuvvvwwwxxxyyyzzz{{{|||}}}~~~!, t  .)B@Ûr0|N Jȓ*le )9P`@;doc/freetds/images/callouts/1.gif000064400000001602147633065420012700 0ustar00GIF89a   !!!"""###$$$%%%&&&'''((()))***+++,,,---...///000111222333444555666777888999:::;;;<<<===>>>???@@@AAABBBCCCDDDEEEFFFGGGHHHIIIJJJKKKLLLMMMNNNOOOPPPQQQRRRSSSTTTUUUVVVWWWXXXYYYZZZ[[[\\\]]]^^^___```aaabbbcccdddeeefffggghhhiiijjjkkklllmmmnnnooopppqqqrrrssstttuuuvvvwwwxxxyyyzzz{{{|||}}}~~~!, _G)98\ 9 =F##K#N+#%/cI3&{(D-  ;doc/freetds/images/callouts/7.gif000064400000001616147633065420012713 0ustar00GIF89a   !!!"""###$$$%%%&&&'''((()))***+++,,,---...///000111222333444555666777888999:::;;;<<<===>>>???@@@AAABBBCCCDDDEEEFFFGGGHHHIIIJJJKKKLLLMMMNNNOOOPPPQQQRRRSSSTTTUUUVVVWWWXXXYYYZZZ[[[\\\]]]^^^___```aaabbbcccdddeeefffggghhhiiijjjkkklllmmmnnnooopppqqqrrrssstttuuuvvvwwwxxxyyyzzz{{{|||}}}~~~!, k %%E % wO  !@qN ƽ^Bp"J&E2G {͐jD2?)0c ) Ykh BN9 HQT`@;doc/freetds/images/callouts/4.gif000064400000001623147633065420012706 0ustar00GIF89a   !!!"""###$$$%%%&&&'''((()))***+++,,,---...///000111222333444555666777888999:::;;;<<<===>>>???@@@AAABBBCCCDDDEEEFFFGGGHHHIIIJJJKKKLLLMMMNNNOOOPPPQQQRRRSSSTTTUUUVVVWWWXXXYYYZZZ[[[\\\]]]^^^___```aaabbbcccdddeeefffggghhhiiijjjkkklllmmmnnnooopppqqqrrrssstttuuuvvvwwwxxxyyyzzz{{{|||}}}~~~!, p l%%E % 8'C%8qC(jtH"VލC- [e)1r A1 rcG3?2㨷5{(K;doc/freetds/images/callouts/9.gif000064400000001637147633065420012720 0ustar00GIF89a   !!!"""###$$$%%%&&&'''((()))***+++,,,---...///000111222333444555666777888999:::;;;<<<===>>>???@@@AAABBBCCCDDDEEEFFFGGGHHHIIIJJJKKKLLLMMMNNNOOOPPPQQQRRRSSSTTTUUUVVVWWWXXXYYYZZZ[[[\\\]]]^^^___```aaabbbcccdddeeefffggghhhiiijjjkkklllmmmnnnooopppqqqrrrssstttuuuvvvwwwxxxyyyzzz{{{|||}}}~~~!, | l%%E) wO ݹsr:̉5Jcr/92@>>???@@@AAABBBCCCDDDEEEFFFGGGHHHIIIJJJKKKLLLMMMNNNOOOPPPQQQRRRSSSTTTUUUVVVWWWXXXYYYZZZ[[[\\\]]]^^^___```aaabbbcccdddeeefffggghhhiiijjjkkklllmmmnnnooopppqqqrrrssstttuuuvvvwwwxxxyyyzzz{{{|||}}}~~~!, z l%%E %  )8'!RC ǽVÀ],+"G108<ΙMثCg`] 2w{Hqɜ/SxSxK1 ;doc/freetds/images/tip.gif000064400000002005147633065420011504 0ustar00GIF87a  !!!"""###$$$%%%&&&'''((()))***+++,,,---...///000111222333444555666777888999:::;;;<<<===>>>???@@@AAABBBCCCDDDEEEFFFGGGHHHIIIJJJKKKLLLMMMNNNOOOPPPQQQRRRSSSTTTUUUVVVWWWXXXYYYZZZ[[[\\\]]]^^^___```aaabbbcccdddeeefffggghhhiiijjjkkklllmmmnnnooopppqqqrrrssstttuuuvvvwwwxxxyyyzzz{{{|||}}}~~~, HA*xX)J"Btvoa{&!%J,2M3QUQsj)TK!s W&tV{{BYTI7yFЛх*^Uh k`֔x˞ )Hv[?]m&V'^BxpBÀ#DẂV2 g-Oz3& kQ«k='ۘɔ=x"m|_@;doc/freetds/images/important.gif000064400000002071147633065420012730 0ustar00GIF87a)))999BB1BBBJJJRRRZZ)ccccRccckkBkkkssR{{{9{ZZc{c!9k{JRZZsRck!19R!)1Zc{1B19J!,HpA*ܲĆ ""Bae!A+3,|ҤcG,0$WRTC dd͔ML9& |ܰs 5WR@ARM< $J rSG 8Pܼ"i'c9,""LdOW`+D2ͫ2$ou;w ;doc/freetds/images/note.gif000064400000002056147633065420011663 0ustar00GIF87a  !!!"""###$$$%%%&&&'''((()))***+++,,,---...///000111222333444555666777888999:::;;;<<<===>>>???@@@AAABBBCCCDDDEEEFFFGGGHHHIIIJJJKKKLLLMMMNNNOOOPPPQQQRRRSSSTTTUUUVVVWWWXXXYYYZZZ[[[\\\]]]^^^___```aaabbbcccdddeeefffggghhhiiijjjkkklllmmmnnnooopppqqqrrrssstttuuuvvvwwwxxxyyyzzz{{{|||}}}~~~, HA*ثR:[1F{1J&R<(Zʓ[Hi&L5 :+ub)LS`QzRAJ5kr͚3F Ftn9 <Ҙ9Mu lFQE=5k-5Szҿw=QbsT¸$eJ{Jq\ǫ=@W˚Z!l3ƦR<-%3!c[B*'{ƚxyǨ^Sj lĊQ9o;6$H;doc/freetds/userguide/index.html000064400000000125147633065420012746 0ustar00

at www.freetds.org man/man1/nghttpx.1000064400000270453147633146710007760 0ustar00.\" Man page generated from reStructuredText. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "NGHTTPX" "1" "Apr 04, 2024" "1.61.0" "nghttp2" .SH NAME nghttpx \- HTTP/2 proxy .SH SYNOPSIS .sp \fBnghttpx\fP [OPTIONS]... [ ] .SH DESCRIPTION .sp A reverse proxy for HTTP/3, HTTP/2, and HTTP/1. .INDENT 0.0 .TP .B Set path to server\(aqs private key. Required unless \(dqno\-tls\(dq parameter is used in \fI\%\-\-frontend\fP option. .UNINDENT .INDENT 0.0 .TP .B Set path to server\(aqs certificate. Required unless \(dqno\-tls\(dq parameter is used in \fI\%\-\-frontend\fP option. To make OCSP stapling work, this must be an absolute path. .UNINDENT .SH OPTIONS .sp The options are categorized into several groups. .SS Connections .INDENT 0.0 .TP .B \-b, \-\-backend=(,|unix:)[;[[:...]][[;]...] 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 \(dqunix:\(dq (e.g., unix:/var/run/backend.sock). .sp Optionally, if 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. consists of path, host + path or just host. The path must start with \(dq\fI/\fP\(dq. If it ends with \(dq\fI/\fP\(dq, it matches all request path in its subtree. To deal with the request to the directory without trailing slash, the path which ends with \(dq\fI/\fP\(dq also matches the request path which only lacks trailing \(aq\fI/\fP\(aq (e.g., path \(dq\fI/foo/\fP\(dq matches request path \(dq\fI/foo\fP\(dq). If it does not end with \(dq\fI/\fP\(dq, 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 \(dqsni\-fwd\(dq parameter enabled, SNI host is used instead of a request host. If host alone is given, \(dq\fI/\fP\(dq is appended to it, so that it matches all request paths under the host (e.g., specifying \(dqnghttp2.org\(dq equals to \(dqnghttp2.org/\(dq). CONNECT method is treated specially. It does not have path, and we don\(aqt allow empty path. To workaround this, we assume that CONNECT method has \(dq\fI/\fP\(dq as path. .sp Patterns with host take precedence over patterns with just path. Then, longer patterns take precedence over shorter ones. .sp Host can include \(dq*\(dq in the left most position to indicate wildcard match (only suffix match is done). The \(dq*\(dq must match at least one character. For example, host pattern \(dq*.nghttp2.org\(dq matches against \(dqwww.nghttp2.org\(dq and \(dqgit.ngttp2.org\(dq, but does not match against \(dqnghttp2.org\(dq. The exact hosts match takes precedence over the wildcard hosts match. .sp If path part ends with \(dq*\(dq, 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,\(dq\fI/\fP\(dq. 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 \(dq*\(dq as prefix, and are strictly longer than wildcard path without last \(dq*\(dq are matched. \(dq*\(dq must match at least one character. For example, the pattern \(dq\fI/foo*\fP\(dq matches \(dq\fI/foo/\fP\(dq and \(dq\fI/foobar\fP\(dq. But it does not match \(dq\fI/foo\fP\(dq, or \(dq\fI/fo\fP\(dq. .sp If is omitted or empty string, \(dq\fI/\fP\(dq is used as pattern, which matches all request paths (catch\-all pattern). The catch\-all backend must be given. .sp 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 (\(dq..\(dq and \(dq.\(dq) are resolved and removed. .sp For example, \fI\%\-b\fP\(aq127.0.0.1,8080;nghttp2.org/httpbin/\(aq matches the request host \(dqnghttp2.org\(dq and the request path \(dq\fI/httpbin/get\fP\(dq, but does not match the request host \(dqnghttp2.org\(dq and the request path \(dq\fI/index.html\fP\(dq. .sp The multiple s can be specified, delimiting them by \(dq:\(dq. Specifying \fI\%\-b\fP\(aq127.0.0.1,8080;nghttp2.org:www.nghttp2.org\(aq has the same effect to specify \fI\%\-b\fP\(aq127.0.0.1,8080;nghttp2.org\(aq and \fI\%\-b\fP\(aq127.0.0.1,8080;www.nghttp2.org\(aq. .sp The backend addresses sharing same are grouped together forming load balancing group. .sp Several parameters are accepted after . The parameters are delimited by \(dq;\(dq. The available parameters are: \(dqproto=\(dq, \(dqtls\(dq, \(dqsni=\(dq, \(dqfall=\(dq, \(dqrise=\(dq, \(dqaffinity=\(dq, \(dqdns\(dq, \(dqredirect\-if\-not\-tls\(dq, \(dqupgrade\-scheme\(dq, \(dqmruby=\(dq, \(dqread\-timeout=\(dq, \(dqwrite\-timeout=\(dq, \(dqgroup=\(dq, \(dqgroup\-weight=\(dq, \(dqweight=\(dq, and \(dqdnf\(dq. The parameter consists of keyword, and optionally followed by \(dq=\(dq and value. For example, the parameter \(dqproto=h2\(dq consists of the keyword \(dqproto\(dq and value \(dqh2\(dq. The parameter \(dqtls\(dq consists of the keyword \(dqtls\(dq without value. Each parameter is described as follows. .sp The backend application protocol can be specified using optional \(dqproto\(dq parameter, and in the form of \(dqproto=\(dq. should be one of the following list without quotes: \(dqh2\(dq, \(dqhttp/1.1\(dq. The default value of is \(dqhttp/1.1\(dq. Note that usually \(dqh2\(dq refers to HTTP/2 over TLS. But in this option, it may mean HTTP/2 over cleartext TCP unless \(dqtls\(dq keyword is used (see below). .sp TLS can be enabled by specifying optional \(dqtls\(dq parameter. TLS is not enabled by default. .sp With \(dqsni=\(dq parameter, it can override the TLS SNI field value with given . This will default to the backend name .sp The feature to detect whether backend is online or offline can be enabled using optional \(dqfall\(dq and \(dqrise\(dq parameters. Using \(dqfall=\(dq parameter, if nghttpx cannot connect to a this backend times in a row, this backend is assumed to be offline, and it is excluded from load balancing. If 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 \(dqrise=\(dq 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 times in a row, the backend is assumed to be online, and it is now eligible for load balancing target. If is 0, a backend is permanently offline, once it goes in that state, and this is the default behaviour. .sp The session affinity is enabled using \(dqaffinity=\(dq parameter. If \(dqip\(dq is given in , client IP based session affinity is enabled. If \(dqcookie\(dq is given in , cookie based session affinity is enabled. If \(dqnone\(dq is given in , session affinity is disabled, and this is the default. The session affinity is enabled per . If at least one backend has \(dqaffinity\(dq parameter, and its is not \(dqnone\(dq, session affinity is enabled for all backend servers sharing the same . It is advised to set \(dqaffinity\(dq 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. .sp If \(dqaffinity=cookie\(dq is used, the additional configuration is required. \(dqaffinity\-cookie\-name=\(dq must be used to specify a name of cookie to use. Optionally, \(dqaffinity\-cookie\-path=\(dq can be used to specify a path which cookie is applied. The optional \(dqaffinity\-cookie\-secure=\(dq controls the Secure attribute of a cookie. The default value is \(dqauto\(dq, and the Secure attribute is determined by a request scheme. If a request scheme is \(dqhttps\(dq, then Secure attribute is set. Otherwise, it is not set. If is \(dqyes\(dq, the Secure attribute is always set. If is \(dqno\(dq, the Secure attribute is always omitted. \(dqaffinity\-cookie\-stickiness=\(dq controls stickiness of this affinity. If is \(dqloose\(dq, removing or adding a backend server might break the affinity and the request might be forwarded to a different backend server. If is \(dqstrict\(dq, 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. defaults to \(dqloose\(dq. .sp By default, name resolution of backend host name is done at start up, or reloading configuration. If \(dqdns\(dq parameter is given, name resolution takes place dynamically. This is useful if backend address changes frequently. If \(dqdns\(dq is given, name resolution of backend host name at start up, or reloading configuration is skipped. .sp If \(dqredirect\-if\-not\-tls\(dq parameter is used, the matched backend requires that frontend connection is TLS encrypted. If it isn\(aqt, 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 \fI\%\-\-redirect\-https\-port\fP option. If at least one backend has \(dqredirect\-if\-not\-tls\(dq parameter, this feature is enabled for all backend servers sharing the same . It is advised to set \(dqredirect\-if\-no\-tls\(dq parameter to all backends explicitly if this feature is desired. .sp If \(dqupgrade\-scheme\(dq parameter is used along with \(dqtls\(dq parameter, HTTP/2 :scheme pseudo header field is changed to \(dqhttps\(dq from \(dqhttp\(dq when forwarding a request to this particular backend. This is a workaround for a backend server which requires \(dqhttps\(dq :scheme pseudo header field on TLS encrypted connection. .sp \(dqmruby=\(dq 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. .sp \(dqread\-timeout=\(dq and \(dqwrite\-timeout=\(dq 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, \fI\%\-\-backend\-read\-timeout\fP and \fI\%\-\-backend\-write\-timeout\fP are used. .sp \(dqgroup=\(dq 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. \(dqgroup\-weight=\(dq parameter specifies the weight of the group. The higher weight gets more frequently selected by the load balancing algorithm. must be [1, 256] inclusive. The weight 8 has 4 times more weight than 2. must be the same for all addresses which share the same . If \(dqgroup\-weight\(dq is omitted in an address, but the other address which belongs to the same group specifies \(dqgroup\-weight\(dq, its weight is used. If no \(dqgroup\-weight\(dq is specified for all addresses, the weight of a group becomes 1. \(dqgroup\(dq and \(dqgroup\-weight\(dq are ignored if session affinity is enabled. .sp \(dqweight=\(dq 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. must be [1, 256] inclusive. The weight 8 has 4 times more weight than weight 2. If this parameter is omitted, weight becomes 1. \(dqweight\(dq is ignored if session affinity is enabled. .sp If \(dqdnf\(dq 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 \(dqmruby=\(dq parameter above). \(dqdnf\(dq is an abbreviation of \(dqdo not forward\(dq. .sp Since \(dq;\(dq and \(dq:\(dq are used as delimiter, must not contain these characters. In order to include \(dq:\(dq in , one has to specify \(dq%3A\(dq (which is percent\-encoded from of \(dq:\(dq) instead. Since \(dq;\(dq has special meaning in shell, the option value must be quoted. .sp Default: \fB127.0.0.1,80\fP .UNINDENT .INDENT 0.0 .TP .B \-f, \-\-frontend=(,|unix:)[[;]...] Set frontend host and port. If is \(aq*\(aq, it assumes all addresses including both IPv4 and IPv6. UNIX domain socket can be specified by prefixing path name with \(dqunix:\(dq (e.g., unix:/var/run/nghttpx.sock). This option can be used multiple times to listen to multiple addresses. .sp This option can take 0 or more parameters, which are described below. Note that \(dqapi\(dq and \(dqhealthmon\(dq parameters are mutually exclusive. .sp Optionally, TLS can be disabled by specifying \(dqno\-tls\(dq parameter. TLS is enabled by default. .sp If \(dqsni\-fwd\(dq 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 \fI\%\-\-backend\fP option about the pattern match. .sp To make this frontend as API endpoint, specify \(dqapi\(dq 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. .sp To make this frontend as health monitor endpoint, specify \(dqhealthmon\(dq parameter. This is disabled by default. Any requests which come through this address are replied with 200 HTTP status, without no body. .sp To accept PROXY protocol version 1 and 2 on frontend connection, specify \(dqproxyproto\(dq parameter. This is disabled by default. .sp To receive HTTP/3 (QUIC) traffic, specify \(dqquic\(dq parameter. It makes nghttpx listen on UDP port rather than TCP port. UNIX domain socket, \(dqapi\(dq, and \(dqhealthmon\(dq parameters cannot be used with \(dqquic\(dq parameter. .sp Default: \fB*,3000\fP .UNINDENT .INDENT 0.0 .TP .B \-\-backlog= Set listen backlog size. .sp Default: \fB65536\fP .UNINDENT .INDENT 0.0 .TP .B \-\-backend\-address\-family=(auto|IPv4|IPv6) Specify address family of backend connections. If \(dqauto\(dq is given, both IPv4 and IPv6 are considered. If \(dqIPv4\(dq is given, only IPv4 address is considered. If \(dqIPv6\(dq is given, only IPv6 address is considered. .sp Default: \fBauto\fP .UNINDENT .INDENT 0.0 .TP .B \-\-backend\-http\-proxy\-uri= Specify proxy URI in the form \fI\%http:/\fP/[:@]:. If a proxy requires authentication, specify and . 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 \fI\%\-\-backend\-read\-timeout\fP and \fI\%\-\-backend\-write\-timeout\fP options. .UNINDENT .SS Performance .INDENT 0.0 .TP .B \-n, \-\-workers= Set the number of worker threads. .sp Default: \fB1\fP .UNINDENT .INDENT 0.0 .TP .B \-\-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. .UNINDENT .INDENT 0.0 .TP .B \-\-read\-rate= Set maximum average read rate on frontend connection. Setting 0 to this option means read rate is unlimited. .sp Default: \fB0\fP .UNINDENT .INDENT 0.0 .TP .B \-\-read\-burst= Set maximum read burst size on frontend connection. Setting 0 to this option means read burst size is unlimited. .sp Default: \fB0\fP .UNINDENT .INDENT 0.0 .TP .B \-\-write\-rate= Set maximum average write rate on frontend connection. Setting 0 to this option means write rate is unlimited. .sp Default: \fB0\fP .UNINDENT .INDENT 0.0 .TP .B \-\-write\-burst= Set maximum write burst size on frontend connection. Setting 0 to this option means write burst size is unlimited. .sp Default: \fB0\fP .UNINDENT .INDENT 0.0 .TP .B \-\-worker\-read\-rate= Set maximum average read rate on frontend connection per worker. Setting 0 to this option means read rate is unlimited. Not implemented yet. .sp Default: \fB0\fP .UNINDENT .INDENT 0.0 .TP .B \-\-worker\-read\-burst= Set maximum read burst size on frontend connection per worker. Setting 0 to this option means read burst size is unlimited. Not implemented yet. .sp Default: \fB0\fP .UNINDENT .INDENT 0.0 .TP .B \-\-worker\-write\-rate= Set maximum average write rate on frontend connection per worker. Setting 0 to this option means write rate is unlimited. Not implemented yet. .sp Default: \fB0\fP .UNINDENT .INDENT 0.0 .TP .B \-\-worker\-write\-burst= Set maximum write burst size on frontend connection per worker. Setting 0 to this option means write burst size is unlimited. Not implemented yet. .sp Default: \fB0\fP .UNINDENT .INDENT 0.0 .TP .B \-\-worker\-frontend\-connections= Set maximum number of simultaneous connections frontend accepts. Setting 0 means unlimited. .sp Default: \fB0\fP .UNINDENT .INDENT 0.0 .TP .B \-\-backend\-connections\-per\-host= Set maximum number of backend concurrent connections (and/or streams in case of HTTP/2) per origin host. This option is meaningful when \fI\%\-\-http2\-proxy\fP 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 \fI\%\-\-backend\-connections\-per\-frontend\fP\&. .sp Default: \fB8\fP .UNINDENT .INDENT 0.0 .TP .B \-\-backend\-connections\-per\-frontend= 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 \fI\%\-\-http2\-proxy\fP option, use \fI\%\-\-backend\-connections\-per\-host\fP\&. .sp Default: \fB0\fP .UNINDENT .INDENT 0.0 .TP .B \-\-rlimit\-nofile= Set maximum number of open files (RLIMIT_NOFILE) to . If 0 is given, nghttpx does not set the limit. .sp Default: \fB0\fP .UNINDENT .INDENT 0.0 .TP .B \-\-rlimit\-memlock= Set maximum number of bytes of memory that may be locked into RAM. If 0 is given, nghttpx does not set the limit. .sp Default: \fB0\fP .UNINDENT .INDENT 0.0 .TP .B \-\-backend\-request\-buffer= Set buffer size used to store backend request. .sp Default: \fB16K\fP .UNINDENT .INDENT 0.0 .TP .B \-\-backend\-response\-buffer= Set buffer size used to store backend response. .sp Default: \fB128K\fP .UNINDENT .INDENT 0.0 .TP .B \-\-fastopen= Enables \(dqTCP Fast Open\(dq 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. .sp Default: \fB0\fP .UNINDENT .INDENT 0.0 .TP .B \-\-no\-kqueue Don\(aqt use kqueue. This option is only applicable for the platforms which have kqueue. For other platforms, this option will be simply ignored. .UNINDENT .SS Timeout .INDENT 0.0 .TP .B \-\-frontend\-http2\-idle\-timeout= Specify idle timeout for HTTP/2 frontend connection. If no active streams exist for this duration, connection is closed. .sp Default: \fB3m\fP .UNINDENT .INDENT 0.0 .TP .B \-\-frontend\-http3\-idle\-timeout= Specify idle timeout for HTTP/3 frontend connection. If no active streams exist for this duration, connection is closed. .sp Default: \fB3m\fP .UNINDENT .INDENT 0.0 .TP .B \-\-frontend\-write\-timeout= Specify write timeout for all frontend connections. .sp Default: \fB30s\fP .UNINDENT .INDENT 0.0 .TP .B \-\-frontend\-keep\-alive\-timeout= Specify keep\-alive timeout for frontend HTTP/1 connection. .sp Default: \fB1m\fP .UNINDENT .INDENT 0.0 .TP .B \-\-frontend\-header\-timeout= 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. .sp Default: \fB1m\fP .UNINDENT .INDENT 0.0 .TP .B \-\-stream\-read\-timeout= Specify read timeout for HTTP/2 streams. 0 means no timeout. .sp Default: \fB0\fP .UNINDENT .INDENT 0.0 .TP .B \-\-stream\-write\-timeout= Specify write timeout for HTTP/2 streams. 0 means no timeout. .sp Default: \fB1m\fP .UNINDENT .INDENT 0.0 .TP .B \-\-backend\-read\-timeout= Specify read timeout for backend connection. .sp Default: \fB1m\fP .UNINDENT .INDENT 0.0 .TP .B \-\-backend\-write\-timeout= Specify write timeout for backend connection. .sp Default: \fB30s\fP .UNINDENT .INDENT 0.0 .TP .B \-\-backend\-connect\-timeout= Specify timeout before establishing TCP connection to backend. .sp Default: \fB30s\fP .UNINDENT .INDENT 0.0 .TP .B \-\-backend\-keep\-alive\-timeout= Specify keep\-alive timeout for backend HTTP/1 connection. .sp Default: \fB2s\fP .UNINDENT .INDENT 0.0 .TP .B \-\-listener\-disable\-timeout= After accepting connection failed, connection listener is disabled for a given amount of time. Specifying 0 disables this feature. .sp Default: \fB30s\fP .UNINDENT .INDENT 0.0 .TP .B \-\-frontend\-http2\-setting\-timeout= Specify timeout before SETTINGS ACK is received from client. .sp Default: \fB10s\fP .UNINDENT .INDENT 0.0 .TP .B \-\-backend\-http2\-settings\-timeout= Specify timeout before SETTINGS ACK is received from backend server. .sp Default: \fB10s\fP .UNINDENT .INDENT 0.0 .TP .B \-\-backend\-max\-backoff= Specify maximum backoff interval. This is used when doing health check against offline backend (see \(dqfail\(dq parameter in \fI\%\-\-backend\fP 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. .sp Default: \fB2m\fP .UNINDENT .SS SSL/TLS .INDENT 0.0 .TP .B \-\-ciphers= 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 \fI\%\-\-tls13\-ciphers\fP for TLSv1.3. .sp Default: \fBECDHE\-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\fP .UNINDENT .INDENT 0.0 .TP .B \-\-tls13\-ciphers= 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 \fI\%\-\-ciphers\fP for TLSv1.2 or earlier. .sp Default: \fBTLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256\fP .UNINDENT .INDENT 0.0 .TP .B \-\-client\-ciphers= 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 \fI\%\-\-tls13\-client\-ciphers\fP for TLSv1.3. .sp Default: \fBECDHE\-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\fP .UNINDENT .INDENT 0.0 .TP .B \-\-tls13\-client\-ciphers= 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 \fI\%\-\-tls13\-client\-ciphers\fP for TLSv1.2 or earlier. .sp Default: \fBTLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256\fP .UNINDENT .INDENT 0.0 .TP .B \-\-ecdh\-curves= Set supported curve list for frontend connections. 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. .sp Default: \fBX25519:P\-256:P\-384:P\-521\fP .UNINDENT .INDENT 0.0 .TP .B \-k, \-\-insecure Don\(aqt verify backend server\(aqs certificate if TLS is enabled for backend connections. .UNINDENT .INDENT 0.0 .TP .B \-\-cacert= Set path to trusted CA certificate file. It is used in backend TLS connections to verify peer\(aqs certificate. It is also used to verify OCSP response from the script set by \fI\%\-\-fetch\-ocsp\-response\-file\fP\&. 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. .UNINDENT .INDENT 0.0 .TP .B \-\-private\-key\-passwd\-file= Path to file that contains password for the server\(aqs private key. If none is given and the private key is password protected it\(aqll be requested interactively. .UNINDENT .INDENT 0.0 .TP .B \-\-subcert=:[[;]...] 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, must be absolute path. .sp Additional parameter can be specified in . The available is \(dqsct\-dir=

\(dq. .sp \(dqsct\-dir=\(dq 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 \fI\%\-\-tls\-sct\-dir\fP option. .UNINDENT .INDENT 0.0 .TP .B \-\-dh\-param\-file= Path to file that contains DH parameters in PEM format. Without this option, DHE cipher suites are not available. .UNINDENT .INDENT 0.0 .TP .B \-\-alpn\-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. .sp Default: \fBh2,h2\-16,h2\-14,http/1.1\fP .UNINDENT .INDENT 0.0 .TP .B \-\-verify\-client Require and verify client certificate. .UNINDENT .INDENT 0.0 .TP .B \-\-verify\-client\-cacert= Path to file that contains CA certificates to verify client certificate. The file must be in PEM format. It can contain multiple certificates. .UNINDENT .INDENT 0.0 .TP .B \-\-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. .UNINDENT .INDENT 0.0 .TP .B \-\-client\-private\-key\-file= Path to file that contains client private key used in backend client authentication. .UNINDENT .INDENT 0.0 .TP .B \-\-client\-cert\-file= Path to file that contains client certificate used in backend client authentication. .UNINDENT .INDENT 0.0 .TP .B \-\-tls\-min\-proto\-version= Specify minimum SSL/TLS protocol. The name matching is done in case\-insensitive manner. The versions between \fI\%\-\-tls\-min\-proto\-version\fP and \fI\%\-\-tls\-max\-proto\-version\fP are enabled. If the protocol list advertised by client does not overlap this range, you will receive the error message \(dqunknown protocol\(dq. If a protocol version lower than TLSv1.2 is specified, make sure that the compatible ciphers are included in \fI\%\-\-ciphers\fP 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 .sp Default: \fBTLSv1.2\fP .UNINDENT .INDENT 0.0 .TP .B \-\-tls\-max\-proto\-version= Specify maximum SSL/TLS protocol. The name matching is done in case\-insensitive manner. The versions between \fI\%\-\-tls\-min\-proto\-version\fP and \fI\%\-\-tls\-max\-proto\-version\fP are enabled. If the protocol list advertised by client does not overlap this range, you will receive the error message \(dqunknown protocol\(dq. The available versions are: TLSv1.3, TLSv1.2, TLSv1.1, and TLSv1.0 .sp Default: \fBTLSv1.3\fP .UNINDENT .INDENT 0.0 .TP .B \-\-tls\-ticket\-key\-file= Path to file that contains random data to construct TLS session ticket parameters. If aes\-128\-cbc is given in \fI\%\-\-tls\-ticket\-key\-cipher\fP, the file must contain exactly 48 bytes. If aes\-256\-cbc is given in \fI\%\-\-tls\-ticket\-key\-cipher\fP, 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. .UNINDENT .INDENT 0.0 .TP .B \-\-tls\-ticket\-key\-memcached=,[;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 \(dqTLS SESSION TICKET RESUMPTION\(dq section in manual page to know the data format in memcached entry. Optionally, memcached connection can be encrypted with TLS by specifying \(dqtls\(dq parameter. .UNINDENT .INDENT 0.0 .TP .B \-\-tls\-ticket\-key\-memcached\-address\-family=(auto|IPv4|IPv6) Specify address family of memcached connections to get TLS ticket keys. If \(dqauto\(dq is given, both IPv4 and IPv6 are considered. If \(dqIPv4\(dq is given, only IPv4 address is considered. If \(dqIPv6\(dq is given, only IPv6 address is considered. .sp Default: \fBauto\fP .UNINDENT .INDENT 0.0 .TP .B \-\-tls\-ticket\-key\-memcached\-interval= Set interval to get TLS ticket keys from memcached. .sp Default: \fB10m\fP .UNINDENT .INDENT 0.0 .TP .B \-\-tls\-ticket\-key\-memcached\-max\-retry= Set maximum number of consecutive retries before abandoning TLS ticket key retrieval. If this number is reached, the attempt is considered as failure, and \(dqfailure\(dq count is incremented by 1, which contributed to the value controlled \fI\%\-\-tls\-ticket\-key\-memcached\-max\-fail\fP option. .sp Default: \fB3\fP .UNINDENT .INDENT 0.0 .TP .B \-\-tls\-ticket\-key\-memcached\-max\-fail= Set maximum number of consecutive failure before disabling TLS ticket until next scheduled key retrieval. .sp Default: \fB2\fP .UNINDENT .INDENT 0.0 .TP .B \-\-tls\-ticket\-key\-cipher= Specify cipher to encrypt TLS session ticket. Specify either aes\-128\-cbc or aes\-256\-cbc. By default, aes\-128\-cbc is used. .UNINDENT .INDENT 0.0 .TP .B \-\-tls\-ticket\-key\-memcached\-cert\-file= Path to client certificate for memcached connections to get TLS ticket keys. .UNINDENT .INDENT 0.0 .TP .B \-\-tls\-ticket\-key\-memcached\-private\-key\-file= Path to client private key for memcached connections to get TLS ticket keys. .UNINDENT .INDENT 0.0 .TP .B \-\-fetch\-ocsp\-response\-file= Path to fetch\-ocsp\-response script file. It should be absolute path. .sp Default: \fB/usr/local/share/nghttp2/fetch\-ocsp\-response\fP .UNINDENT .INDENT 0.0 .TP .B \-\-ocsp\-update\-interval= Set interval to update OCSP response cache. .sp Default: \fB4h\fP .UNINDENT .INDENT 0.0 .TP .B \-\-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. .UNINDENT .INDENT 0.0 .TP .B \-\-no\-verify\-ocsp nghttpx does not verify OCSP response. .UNINDENT .INDENT 0.0 .TP .B \-\-no\-ocsp Disable OCSP stapling. .UNINDENT .INDENT 0.0 .TP .B \-\-tls\-session\-cache\-memcached=,[;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 \(dqtls\(dq parameter. .UNINDENT .INDENT 0.0 .TP .B \-\-tls\-session\-cache\-memcached\-address\-family=(auto|IPv4|IPv6) Specify address family of memcached connections to store session cache. If \(dqauto\(dq is given, both IPv4 and IPv6 are considered. If \(dqIPv4\(dq is given, only IPv4 address is considered. If \(dqIPv6\(dq is given, only IPv6 address is considered. .sp Default: \fBauto\fP .UNINDENT .INDENT 0.0 .TP .B \-\-tls\-session\-cache\-memcached\-cert\-file= Path to client certificate for memcached connections to store session cache. .UNINDENT .INDENT 0.0 .TP .B \-\-tls\-session\-cache\-memcached\-private\-key\-file= Path to client private key for memcached connections to store session cache. .UNINDENT .INDENT 0.0 .TP .B \-\-tls\-dyn\-rec\-warmup\-threshold= 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 \fI\%\-\-tls\-dyn\-rec\-idle\-timeout\fP 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. .sp Default: \fB1M\fP .UNINDENT .INDENT 0.0 .TP .B \-\-tls\-dyn\-rec\-idle\-timeout= Specify TLS dynamic record size behaviour timeout. See \fI\%\-\-tls\-dyn\-rec\-warmup\-threshold\fP for more information. This behaviour applies to all TLS based frontends, and TLS HTTP/2 backends. .sp Default: \fB1s\fP .UNINDENT .INDENT 0.0 .TP .B \-\-no\-http2\-cipher\-block\-list Allow block listed cipher suite on frontend HTTP/2 connection. See \fI\%https://tools.ietf.org/html/rfc7540#appendix\-A\fP for the complete HTTP/2 cipher suites block list. .UNINDENT .INDENT 0.0 .TP .B \-\-client\-no\-http2\-cipher\-block\-list Allow block listed cipher suite on backend HTTP/2 connection. See \fI\%https://tools.ietf.org/html/rfc7540#appendix\-A\fP for the complete HTTP/2 cipher suites block list. .UNINDENT .INDENT 0.0 .TP .B \-\-tls\-sct\-dir= Specifies the directory where *.sct files exist. All *.sct files in 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 , or certificate option in configuration file. For additional certificates, use \fI\%\-\-subcert\fP option. This option requires OpenSSL >= 1.0.2. .UNINDENT .INDENT 0.0 .TP .B \-\-psk\-secrets= Read list of PSK identity and secrets from . This is used for frontend connection. The each line of input file is formatted as :, where is PSK identity, and is secret in hex. An empty line, and line which starts with \(aq#\(aq 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 \fI\%\-\-ciphers\fP option. The desired PSK cipher suite may be block listed by HTTP/2. To use those cipher suites with HTTP/2, consider to use \fI\%\-\-no\-http2\-cipher\-block\-list\fP option. But be aware its implications. .UNINDENT .INDENT 0.0 .TP .B \-\-client\-psk\-secrets= Read PSK identity and secrets from . This is used for backend connection. The each line of input file is formatted as :, where is PSK identity, and is secret in hex. An empty line, and line which starts with \(aq#\(aq 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 \fI\%\-\-client\-ciphers\fP option. The desired PSK cipher suite may be block listed by HTTP/2. To use those cipher suites with HTTP/2, consider to use \fI\%\-\-client\-no\-http2\-cipher\-block\-list\fP option. But be aware its implications. .UNINDENT .INDENT 0.0 .TP .B \-\-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 \(dqEarly\-Data\(dq header field, using this option makes nghttpx not postpone forwarding request and get full potential of 0\-RTT data. .UNINDENT .INDENT 0.0 .TP .B \-\-tls\-max\-early\-data= Sets the maximum amount of 0\-RTT data that server accepts. .sp Default: \fB16K\fP .UNINDENT .INDENT 0.0 .TP .B \-\-tls\-ktls Enable ktls. For server, ktls is enable if \fI\%\-\-tls\-session\-cache\-memcached\fP is not configured. .UNINDENT .SS HTTP/2 .INDENT 0.0 .TP .B \-c, \-\-frontend\-http2\-max\-concurrent\-streams= Set the maximum number of the concurrent streams in one frontend HTTP/2 session. .sp Default: \fB100\fP .UNINDENT .INDENT 0.0 .TP .B \-\-backend\-http2\-max\-concurrent\-streams= 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. .sp Default: \fB100\fP .UNINDENT .INDENT 0.0 .TP .B \-\-frontend\-http2\-window\-size= Sets the per\-stream initial window size of HTTP/2 frontend connection. .sp Default: \fB65535\fP .UNINDENT .INDENT 0.0 .TP .B \-\-frontend\-http2\-connection\-window\-size= Sets the per\-connection window size of HTTP/2 frontend connection. .sp Default: \fB65535\fP .UNINDENT .INDENT 0.0 .TP .B \-\-backend\-http2\-window\-size= Sets the initial window size of HTTP/2 backend connection. .sp Default: \fB65535\fP .UNINDENT .INDENT 0.0 .TP .B \-\-backend\-http2\-connection\-window\-size= Sets the per\-connection window size of HTTP/2 backend connection. .sp Default: \fB2147483647\fP .UNINDENT .INDENT 0.0 .TP .B \-\-http2\-no\-cookie\-crumbling Don\(aqt crumble cookie header field. .UNINDENT .INDENT 0.0 .TP .B \-\-padding= Add at most 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. .UNINDENT .INDENT 0.0 .TP .B \-\-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. .UNINDENT .INDENT 0.0 .TP .B \-\-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. .UNINDENT .INDENT 0.0 .TP .B \-\-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 \fI\%\-\-frontend\-http2\-connection\-window\-size\fP\&. Since the stream is subject to stream level window size, it should be adjusted using \fI\%\-\-frontend\-http2\-window\-size\fP option as well. This option is only effective on recent Linux platform. .UNINDENT .INDENT 0.0 .TP .B \-\-frontend\-http2\-encoder\-dynamic\-table\-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. .sp Default: \fB4K\fP .UNINDENT .INDENT 0.0 .TP .B \-\-frontend\-http2\-decoder\-dynamic\-table\-size= Specify the maximum dynamic table size of HPACK decoder in the frontend HTTP/2 connection. .sp Default: \fB4K\fP .UNINDENT .INDENT 0.0 .TP .B \-\-backend\-http2\-encoder\-dynamic\-table\-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. .sp Default: \fB4K\fP .UNINDENT .INDENT 0.0 .TP .B \-\-backend\-http2\-decoder\-dynamic\-table\-size= Specify the maximum dynamic table size of HPACK decoder in the backend HTTP/2 connection. .sp Default: \fB4K\fP .UNINDENT .SS Mode .INDENT 0.0 .TP .B (default mode) Accept HTTP/2, and HTTP/1.1 over SSL/TLS. \(dqno\-tls\(dq parameter is used in \fI\%\-\-frontend\fP 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. .UNINDENT .INDENT 0.0 .TP .B \-s, \-\-http2\-proxy Like default mode, but enable forward proxy. This is so called HTTP/2 proxy mode. .UNINDENT .SS Logging .INDENT 0.0 .TP .B \-L, \-\-log\-level= Set the severity level of log output. must be one of INFO, NOTICE, WARN, ERROR and FATAL. .sp Default: \fBNOTICE\fP .UNINDENT .INDENT 0.0 .TP .B \-\-accesslog\-file= Set path to write access log. To reopen file, send USR1 signal to nghttpx. .UNINDENT .INDENT 0.0 .TP .B \-\-accesslog\-syslog Send access log to syslog. If this option is used, \fI\%\-\-accesslog\-file\fP option is ignored. .UNINDENT .INDENT 0.0 .TP .B \-\-accesslog\-format= Specify format string for access log. The default format is combined format. The following variables are available: .INDENT 7.0 .IP \(bu 2 $remote_addr: client IP address. .IP \(bu 2 $time_local: local time in Common Log format. .IP \(bu 2 $time_iso8601: local time in ISO 8601 format. .IP \(bu 2 $request: HTTP request line. .IP \(bu 2 $status: HTTP response status code. .IP \(bu 2 $body_bytes_sent: the number of bytes sent to client as response body. .IP \(bu 2 $http_: value of HTTP request header where \(aq_\(aq in is replaced with \(aq\-\(aq. .IP \(bu 2 $remote_port: client port. .IP \(bu 2 $server_port: server port. .IP \(bu 2 $request_time: request processing time in seconds with milliseconds resolution. .IP \(bu 2 $pid: PID of the running process. .IP \(bu 2 $alpn: ALPN identifier of the protocol which generates the response. For HTTP/1, ALPN is always http/1.1, regardless of minor version. .IP \(bu 2 $tls_cipher: cipher used for SSL/TLS connection. .IP \(bu 2 $tls_client_fingerprint_sha256: SHA\-256 fingerprint of client certificate. .IP \(bu 2 $tls_client_fingerprint_sha1: SHA\-1 fingerprint of client certificate. .IP \(bu 2 $tls_client_subject_name: subject name in client certificate. .IP \(bu 2 $tls_client_issuer_name: issuer name in client certificate. .IP \(bu 2 $tls_client_serial: serial number in client certificate. .IP \(bu 2 $tls_protocol: protocol for SSL/TLS connection. .IP \(bu 2 $tls_session_id: session ID for SSL/TLS connection. .IP \(bu 2 $tls_session_reused: \(dqr\(dq if SSL/TLS session was reused. Otherwise, \(dq.\(dq .IP \(bu 2 $tls_sni: SNI server name for SSL/TLS connection. .IP \(bu 2 $backend_host: backend host used to fulfill the request. \(dq\-\(dq if backend host is not available. .IP \(bu 2 $backend_port: backend port used to fulfill the request. \(dq\-\(dq if backend host is not available. .IP \(bu 2 $method: HTTP method .IP \(bu 2 $path: Request path including query. For CONNECT request, authority is recorded. .IP \(bu 2 $path_without_query: $path up to the first \(aq?\(aq character. For CONNECT request, authority is recorded. .IP \(bu 2 $protocol_version: HTTP version (e.g., HTTP/1.1, HTTP/2) .UNINDENT .sp The variable can be enclosed by \(dq{\(dq and \(dq}\(dq for disambiguation (e.g., ${remote_addr}). .sp Default: \fB$remote_addr \- \- [$time_local] \(dq$request\(dq $status $body_bytes_sent \(dq$http_referer\(dq \(dq$http_user_agent\(dq\fP .UNINDENT .INDENT 0.0 .TP .B \-\-accesslog\-write\-early Write access log when response header fields are received from backend rather than when request transaction finishes. .UNINDENT .INDENT 0.0 .TP .B \-\-errorlog\-file= Set path to write error log. To reopen file, send USR1 signal to nghttpx. stderr will be redirected to the error log file unless \fI\%\-\-errorlog\-syslog\fP is used. .sp Default: \fB/dev/stderr\fP .UNINDENT .INDENT 0.0 .TP .B \-\-errorlog\-syslog Send error log to syslog. If this option is used, \fI\%\-\-errorlog\-file\fP option is ignored. .UNINDENT .INDENT 0.0 .TP .B \-\-syslog\-facility= Set syslog facility to . .sp Default: \fBdaemon\fP .UNINDENT .SS HTTP .INDENT 0.0 .TP .B \-\-add\-x\-forwarded\-for Append X\-Forwarded\-For header field to the downstream request. .UNINDENT .INDENT 0.0 .TP .B \-\-strip\-incoming\-x\-forwarded\-for Strip X\-Forwarded\-For header field from inbound client requests. .UNINDENT .INDENT 0.0 .TP .B \-\-no\-add\-x\-forwarded\-proto Don\(aqt append additional X\-Forwarded\-Proto header field to the backend request. If inbound client sets X\-Forwarded\-Proto, and \fI\%\-\-no\-strip\-incoming\-x\-forwarded\-proto\fP option is used, they are passed to the backend. .UNINDENT .INDENT 0.0 .TP .B \-\-no\-strip\-incoming\-x\-forwarded\-proto Don\(aqt strip X\-Forwarded\-Proto header field from inbound client requests. .UNINDENT .INDENT 0.0 .TP .B \-\-add\-forwarded= Append RFC 7239 Forwarded header field with parameters specified in comma delimited list . The supported parameters are \(dqby\(dq, \(dqfor\(dq, \(dqhost\(dq, and \(dqproto\(dq. By default, the value of \(dqby\(dq and \(dqfor\(dq parameters are obfuscated string. See \fI\%\-\-forwarded\-by\fP and \fI\%\-\-forwarded\-for\fP options respectively. Note that nghttpx does not translate non\-standard X\-Forwarded\-* header fields into Forwarded header field, and vice versa. .UNINDENT .INDENT 0.0 .TP .B \-\-strip\-incoming\-forwarded Strip Forwarded header field from inbound client requests. .UNINDENT .INDENT 0.0 .TP .B \-\-forwarded\-by=(obfuscated|ip|) Specify the parameter value sent out with \(dqby\(dq parameter of Forwarded header field. If \(dqobfuscated\(dq is given, the string is randomly generated at startup. If \(dqip\(dq is given, the interface address of the connection, including port number, is sent with \(dqby\(dq parameter. In case of UNIX domain socket, \(dqlocalhost\(dq is used instead of address and port. User can also specify the static obfuscated string. The limitation is that it must start with \(dq_\(dq, and only consists of character set [A\-Za\-z0\-9._\-], as described in RFC 7239. .sp Default: \fBobfuscated\fP .UNINDENT .INDENT 0.0 .TP .B \-\-forwarded\-for=(obfuscated|ip) Specify the parameter value sent out with \(dqfor\(dq parameter of Forwarded header field. If \(dqobfuscated\(dq is given, the string is randomly generated for each client connection. If \(dqip\(dq is given, the remote client address of the connection, without port number, is sent with \(dqfor\(dq parameter. In case of UNIX domain socket, \(dqlocalhost\(dq is used instead of address. .sp Default: \fBobfuscated\fP .UNINDENT .INDENT 0.0 .TP .B \-\-no\-via Don\(aqt append to Via header field. If Via header field is received, it is left unaltered. .UNINDENT .INDENT 0.0 .TP .B \-\-no\-strip\-incoming\-early\-data Don\(aqt strip Early\-Data header field from inbound client requests. .UNINDENT .INDENT 0.0 .TP .B \-\-no\-location\-rewrite Don\(aqt rewrite location header field in default mode. When \fI\%\-\-http2\-proxy\fP is used, location header field will not be altered regardless of this option. .UNINDENT .INDENT 0.0 .TP .B \-\-host\-rewrite Rewrite host and :authority header fields in default mode. When \fI\%\-\-http2\-proxy\fP is used, these headers will not be altered regardless of this option. .UNINDENT .INDENT 0.0 .TP .B \-\-altsvc= Specify protocol ID, port, host and origin of alternative service. , and are optional. Empty and 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: \fI\%\-\-altsvc\fP=\(dqh2,443,,,ma=3600; persist=1\(dq .UNINDENT .INDENT 0.0 .TP .B \-\-http2\-altsvc= Just like \fI\%\-\-altsvc\fP option, but this altsvc is only sent in HTTP/2 frontend. .UNINDENT .INDENT 0.0 .TP .B \-\-add\-request\-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\(aqt replace anything already set. This option can be used several times to specify multiple header fields. Example: \fI\%\-\-add\-request\-header\fP=\(dqfoo: bar\(dq .UNINDENT .INDENT 0.0 .TP .B \-\-add\-response\-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\(aqt replace anything already set. This option can be used several times to specify multiple header fields. Example: \fI\%\-\-add\-response\-header\fP=\(dqfoo: bar\(dq .UNINDENT .INDENT 0.0 .TP .B \-\-request\-header\-field\-buffer= 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. .sp Default: \fB64K\fP .UNINDENT .INDENT 0.0 .TP .B \-\-max\-request\-header\-fields= Set maximum number of incoming HTTP request header fields. If trailer fields exist, they are counted towards this number. .sp Default: \fB100\fP .UNINDENT .INDENT 0.0 .TP .B \-\-response\-header\-field\-buffer= 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. .sp Default: \fB64K\fP .UNINDENT .INDENT 0.0 .TP .B \-\-max\-response\-header\-fields= Set maximum number of incoming HTTP response header fields. If trailer fields exist, they are counted towards this number. .sp Default: \fB500\fP .UNINDENT .INDENT 0.0 .TP .B \-\-error\-page=(|*)= Set file path to custom error page served when nghttpx originally generates HTTP error status code . must be greater than or equal to 400, and at most 599. If \(dq*\(dq is used instead of , it matches all HTTP status code. If error status code comes from backend server, the custom error pages are not used. .UNINDENT .INDENT 0.0 .TP .B \-\-server\-name= Change server response header field value to . .sp Default: \fBnghttpx\fP .UNINDENT .INDENT 0.0 .TP .B \-\-no\-server\-rewrite Don\(aqt rewrite server header field in default mode. When \fI\%\-\-http2\-proxy\fP is used, these headers will not be altered regardless of this option. .UNINDENT .INDENT 0.0 .TP .B \-\-redirect\-https\-port= Specify the port number which appears in Location header field when redirect to HTTPS URI is made due to \(dqredirect\-if\-not\-tls\(dq parameter in \fI\%\-\-backend\fP option. .sp Default: \fB443\fP .UNINDENT .INDENT 0.0 .TP .B \-\-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. .UNINDENT .SS API .INDENT 0.0 .TP .B \-\-api\-max\-request\-body= Set the maximum size of request body for API request. .sp Default: \fB32M\fP .UNINDENT .SS DNS .INDENT 0.0 .TP .B \-\-dns\-cache\-timeout= Set duration that cached DNS results remain valid. Note that nghttpx caches the unsuccessful results as well. .sp Default: \fB10s\fP .UNINDENT .INDENT 0.0 .TP .B \-\-dns\-lookup\-timeout= 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. .sp Default: \fB5s\fP .UNINDENT .INDENT 0.0 .TP .B \-\-dns\-max\-try= Set the number of DNS query before nghttpx gives up name lookup. .sp Default: \fB2\fP .UNINDENT .INDENT 0.0 .TP .B \-\-frontend\-max\-requests= 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. .UNINDENT .SS Debug .INDENT 0.0 .TP .B \-\-frontend\-http2\-dump\-request\-header= Dumps request headers received by HTTP/2 frontend to the file denoted in . 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 \fI\%\-n\fP, where >= 2. .UNINDENT .INDENT 0.0 .TP .B \-\-frontend\-http2\-dump\-response\-header= Dumps response headers sent from HTTP/2 frontend to the file denoted in . 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 \fI\%\-n\fP, where >= 2. .UNINDENT .INDENT 0.0 .TP .B \-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 \fI\%\-n\fP=N, where N >= 2. .UNINDENT .SS Process .INDENT 0.0 .TP .B \-D, \-\-daemon Run in a background. If \fI\%\-D\fP is used, the current working directory is changed to \(aq\fI/\fP\(aq. .UNINDENT .INDENT 0.0 .TP .B \-\-pid\-file= Set path to save PID of this program. .UNINDENT .INDENT 0.0 .TP .B \-\-user= Run this program as . This option is intended to be used to drop root privileges. .UNINDENT .INDENT 0.0 .TP .B \-\-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. .UNINDENT .INDENT 0.0 .TP .B \-\-max\-worker\-processes= 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. .UNINDENT .INDENT 0.0 .TP .B \-\-worker\-process\-grace\-shutdown\-period= 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. .UNINDENT .SS Scripting .INDENT 0.0 .TP .B \-\-mruby\-file= Set mruby script file .UNINDENT .INDENT 0.0 .TP .B \-\-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. .UNINDENT .SS HTTP/3 and QUIC .INDENT 0.0 .TP .B \-\-frontend\-quic\-idle\-timeout= Specify an idle timeout for QUIC connection. .sp Default: \fB30s\fP .UNINDENT .INDENT 0.0 .TP .B \-\-frontend\-quic\-debug\-log Output QUIC debug log to \fI/dev/stderr.\fP .UNINDENT .INDENT 0.0 .TP .B \-\-quic\-bpf\-program\-file= Specify a path to eBPF program file reuseport_kern.o to direct an incoming QUIC UDP datagram to a correct socket. .sp Default: \fB/usr/local/lib/nghttp2/reuseport_kern.o\fP .UNINDENT .INDENT 0.0 .TP .B \-\-frontend\-quic\-early\-data Enable early data on frontend QUIC connections. nghttpx sends \(dqEarly\-Data\(dq 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. .UNINDENT .INDENT 0.0 .TP .B \-\-frontend\-quic\-qlog\-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 \(dq\-\(dq, server Source Connection ID and \(dq.sqlog\(dq. .UNINDENT .INDENT 0.0 .TP .B \-\-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. .UNINDENT .INDENT 0.0 .TP .B \-\-frontend\-quic\-congestion\-controller= Specify a congestion controller algorithm for a frontend QUIC connection. should be either \(dqcubic\(dq or \(dqbbr\(dq. .sp Default: \fBcubic\fP .UNINDENT .INDENT 0.0 .TP .B \-\-frontend\-quic\-secret\-file= 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 \(aq#\(aq 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. .UNINDENT .INDENT 0.0 .TP .B \-\-quic\-server\-id= 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. .UNINDENT .INDENT 0.0 .TP .B \-\-frontend\-quic\-initial\-rtt= Specify the initial RTT of the frontend QUIC connection. .sp Default: \fB333ms\fP .UNINDENT .INDENT 0.0 .TP .B \-\-no\-quic\-bpf Disable eBPF. .UNINDENT .INDENT 0.0 .TP .B \-\-frontend\-http3\-window\-size= Sets the per\-stream initial window size of HTTP/3 frontend connection. .sp Default: \fB256K\fP .UNINDENT .INDENT 0.0 .TP .B \-\-frontend\-http3\-connection\-window\-size= Sets the per\-connection window size of HTTP/3 frontend connection. .sp Default: \fB1M\fP .UNINDENT .INDENT 0.0 .TP .B \-\-frontend\-http3\-max\-window\-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 \fI\%\-\-frontend\-http3\-window\-size\fP and the window size grows up to bytes. .sp Default: \fB6M\fP .UNINDENT .INDENT 0.0 .TP .B \-\-frontend\-http3\-max\-connection\-window\-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 \fI\%\-\-frontend\-http3\-connection\-window\-size\fP and the window size grows up to bytes. .sp Default: \fB8M\fP .UNINDENT .INDENT 0.0 .TP .B \-\-frontend\-http3\-max\-concurrent\-streams= Set the maximum number of the concurrent streams in one frontend HTTP/3 connection. .sp Default: \fB100\fP .UNINDENT .SS Misc .INDENT 0.0 .TP .B \-\-conf= Load configuration from . Please note that nghttpx always tries to read the default configuration file if \fI\%\-\-conf\fP is not given. .sp Default: \fB/etc/nghttpx/nghttpx.conf\fP .UNINDENT .INDENT 0.0 .TP .B \-\-include= Load additional configurations from . File is read when configuration parser encountered this option. This option can be used multiple times, or even recursively. .UNINDENT .INDENT 0.0 .TP .B \-v, \-\-version Print version and exit. .UNINDENT .INDENT 0.0 .TP .B \-h, \-\-help Print this help and exit. .UNINDENT .sp The argument is an integer and an optional unit (e.g., 10K is 10 * 1024). Units are K, M and G (powers of 1024). .sp The 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. .SH FILES .INDENT 0.0 .TP .B \fI/etc/nghttpx/nghttpx.conf\fP The default configuration file path nghttpx searches at startup. The configuration file path can be changed using \fI\%\-\-conf\fP option. .sp Those lines which are staring \fB#\fP are treated as comment. .sp The option name in the configuration file is the long command\-line option name with leading \fB\-\-\fP stripped (e.g., \fBfrontend\fP). Put \fB=\fP between option name and value. Don\(aqt put extra leading or trailing spaces. .sp 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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C add\-request\-header=foo: bar .ft P .fi .UNINDENT .UNINDENT .sp instead of: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C add\-request\-header=\(dqfoo: bar\(dq .ft P .fi .UNINDENT .UNINDENT .sp The options which do not take argument in the command\-line \fItake\fP argument in the configuration file. Specify \fByes\fP as an argument (e.g., \fBhttp2\-proxy=yes\fP). If other string is given, it is ignored. .sp To specify private key and certificate file which are given as positional arguments in command\-line, use \fBprivate\-key\-file\fP and \fBcertificate\-file\fP\&. .sp \fI\%\-\-conf\fP option cannot be used in the configuration file and will be ignored if specified. .TP .B Error log Error log is written to stderr by default. It can be configured using \fI\%\-\-errorlog\-file\fP\&. The format of log message is as follows: .sp (:) .INDENT 7.0 .TP .B It is a combination of date and time when the log is written. It is in ISO 8601 format. .TP .B It is a main process ID. .TP .B It is a process ID which writes this log. .TP .B It is a thread ID which writes this log. It would be unique within . .TP .B and They are source file name, and line number which produce this log. .TP .B It is a log message body. .UNINDENT .UNINDENT .SH SIGNALS .INDENT 0.0 .TP .B SIGQUIT Shutdown gracefully. First accept pending connections and stop accepting connection. After all connections are handled, nghttpx exits. .TP .B SIGHUP Reload configuration file given in \fI\%\-\-conf\fP\&. .TP .B SIGUSR1 Reopen log files. .UNINDENT .sp SIGUSR2 .INDENT 0.0 .INDENT 3.5 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. .sp 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. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 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. .UNINDENT .UNINDENT .SH SERVER PUSH .sp nghttpx supports HTTP/2 server push in default mode with Link header field. nghttpx looks for Link header field (\fI\%RFC 5988\fP) in response headers from backend server and extracts URI\-reference with parameter \fBrel=preload\fP (see \fI\%preload\fP) and pushes those URIs to the frontend client. Here is a sample Link header field to initiate server push: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Link: ; rel=preload Link: ; rel=preload .ft P .fi .UNINDENT .UNINDENT .sp Currently, the following restriction is applied for server push: .INDENT 0.0 .IP 1. 3 The associated stream must have method \(dqGET\(dq or \(dqPOST\(dq. The associated stream\(aqs status code must be 200. .UNINDENT .sp This limitation may be loosened in the future release. .sp 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. .sp HTTP/2 server push will be disabled if \fI\%\-\-http2\-proxy\fP is used. .SH UNIX DOMAIN SOCKET .sp nghttpx supports UNIX domain socket with a filename for both frontend and backend connections. .sp 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. .SH OCSP STAPLING .sp OCSP query is done using external Python script \fBfetch\-ocsp\-response\fP, which has been originally developed in Perl as part of h2o project (\fI\%https://github.com/h2o/h2o\fP), and was translated into Python. .sp The script file is usually installed under \fB$(prefix)/share/nghttp2/\fP directory. The actual path to script can be customized using \fI\%\-\-fetch\-ocsp\-response\-file\fP option. .sp If OCSP query is failed, previous OCSP response, if any, is continued to be used. .sp \fI\%\-\-fetch\-ocsp\-response\-file\fP 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 \fBfetch\-ocsp\-response\fP 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 \fBfetch\-ocsp\-response\fP\&. Instead, you can retrieve OCSP response in some way, and store it in a disk or a shared database. Then specify a program in \fI\%\-\-fetch\-ocsp\-response\-file\fP 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 \fBfetch\-ocsp\-response\fP script. .SH TLS SESSION RESUMPTION .sp nghttpx supports TLS session resumption through both session ID and session ticket. .SS SESSION ID RESUMPTION .sp By default, session ID is shared by all worker threads. .sp If \fI\%\-\-tls\-session\-cache\-memcached\fP is given, nghttpx will insert serialized session data to memcached with \fBnghttpx:tls\-session\-cache:\fP + lowercase hex string of session ID as a memcached entry key, with expiry time 12 hours. Session timeout is set to 12 hours. .sp By default, connections to memcached server are not encrypted. To enable encryption, use \fBtls\fP keyword in \fI\%\-\-tls\-session\-cache\-memcached\fP option. .SS TLS SESSION TICKET RESUMPTION .sp 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. .sp If \fI\%\-\-tls\-ticket\-key\-memcached\fP 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 \fBnghttpx:tls\-ticket\-key\fP\&. The data format stored in memcached is the binary format described below: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C +\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ | VERSION (4) |LEN (2)|KEY(48 or 80) ... +\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ ^ | | | +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ (LEN, KEY) pair can be repeated .ft P .fi .UNINDENT .UNINDENT .sp All numbers in the above figure is bytes. All integer fields are network byte order. .sp 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 \fI\%\-\-tls\-ticket\-key\-cipher\fP=aes\-128\-cbc is used, LEN must be 48. If \fI\%\-\-tls\-ticket\-key\-cipher\fP=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. .sp By default, connections to memcached server are not encrypted. To enable encryption, use \fBtls\fP keyword in \fI\%\-\-tls\-ticket\-key\-memcached\fP option. .sp If \fI\%\-\-tls\-ticket\-key\-file\fP 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). .SH CERTIFICATE TRANSPARENCY .sp nghttpx supports TLS \fBsigned_certificate_timestamp\fP extension (\fI\%RFC 6962\fP). The relevant options are \fI\%\-\-tls\-sct\-dir\fP and \fBsct\-dir\fP parameter in \fI\%\-\-subcert\fP\&. They takes a directory, and nghttpx reads all files whose extension is \fB\&.sct\fP under the directory. The \fB*.sct\fP files are encoded as \fBSignedCertificateTimestamp\fP struct described in \fI\%section 3.2 of RFC 69662\fP\&. This format is the same one used by \fI\%nginx\-ct\fP and \fI\%mod_ssl_ct\fP\&. \fI\%ct\-submit\fP can be used to submit certificates to log servers, and obtain the \fBSignedCertificateTimestamp\fP struct which can be used with nghttpx. .SH MRUBY SCRIPTING .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 The current mruby extension API is experimental and not frozen. The API is subject to change in the future release. .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 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. .UNINDENT .UNINDENT .sp 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. .sp There are 2 levels of mruby script invocations: global and per\-pattern. The global mruby script is set by \fI\%\-\-mruby\-file\fP option and is called for all requests. The per\-pattern mruby script is set by \(dqmruby\(dq parameter in \fI\%\-b\fP 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. .sp 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. .sp 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., \fBApp.new\fP). This object is called app object. If app object defines \fBon_req\fP method, it is called with \fI\%Nghttpx::Env\fP object on request hook. Similarly, if app object defines \fBon_resp\fP method, it is called with \fI\%Nghttpx::Env\fP object on response hook. For each method invocation, user can can access \fI\%Nghttpx::Request\fP and \fI\%Nghttpx::Response\fP objects via \fI\%Nghttpx::Env#req\fP and \fI\%Nghttpx::Env#resp\fP respectively. .INDENT 0.0 .TP .B Nghttpx::REQUEST_PHASE Constant to represent request phase. .UNINDENT .INDENT 0.0 .TP .B Nghttpx::RESPONSE_PHASE Constant to represent response phase. .UNINDENT .INDENT 0.0 .TP .B class Nghttpx::Env Object to represent current request specific context. .INDENT 7.0 .TP .B attribute [R] req Return \fI\%Request\fP object. .UNINDENT .INDENT 7.0 .TP .B attribute [R] resp Return \fI\%Response\fP object. .UNINDENT .INDENT 7.0 .TP .B attribute [R] ctx Return Ruby hash object. It persists until request finishes. So values set in request phase hook can be retrieved in response phase hook. .UNINDENT .INDENT 7.0 .TP .B attribute [R] phase Return the current phase. .UNINDENT .INDENT 7.0 .TP .B attribute [R] remote_addr Return IP address of a remote client. If connection is made via UNIX domain socket, this returns the string \(dqlocalhost\(dq. .UNINDENT .INDENT 7.0 .TP .B attribute [R] server_addr Return address of server that accepted the connection. This is a string which specified in \fI\%\-\-frontend\fP option, excluding port number, and not a resolved IP address. For UNIX domain socket, this is a path to UNIX domain socket. .UNINDENT .INDENT 7.0 .TP .B attribute [R] server_port Return port number of the server frontend which accepted the connection from client. .UNINDENT .INDENT 7.0 .TP .B attribute [R] tls_used Return true if TLS is used on the connection. .UNINDENT .INDENT 7.0 .TP .B attribute [R] tls_sni Return the TLS SNI value which client sent in this connection. .UNINDENT .INDENT 7.0 .TP .B attribute [R] tls_client_fingerprint_sha256 Return the SHA\-256 fingerprint of a client certificate. .UNINDENT .INDENT 7.0 .TP .B attribute [R] tls_client_fingerprint_sha1 Return the SHA\-1 fingerprint of a client certificate. .UNINDENT .INDENT 7.0 .TP .B attribute [R] tls_client_issuer_name Return the issuer name of a client certificate. .UNINDENT .INDENT 7.0 .TP .B attribute [R] tls_client_subject_name Return the subject name of a client certificate. .UNINDENT .INDENT 7.0 .TP .B attribute [R] tls_client_serial Return the serial number of a client certificate. .UNINDENT .INDENT 7.0 .TP .B attribute [R] tls_client_not_before Return the start date of a client certificate in seconds since the epoch. .UNINDENT .INDENT 7.0 .TP .B attribute [R] tls_client_not_after Return the end date of a client certificate in seconds since the epoch. .UNINDENT .INDENT 7.0 .TP .B attribute [R] tls_cipher Return a TLS cipher negotiated in this connection. .UNINDENT .INDENT 7.0 .TP .B attribute [R] tls_protocol Return a TLS protocol version negotiated in this connection. .UNINDENT .INDENT 7.0 .TP .B attribute [R] tls_session_id Return a session ID for this connection in hex string. .UNINDENT .INDENT 7.0 .TP .B attribute [R] tls_session_reused Return true if, and only if a SSL/TLS session is reused. .UNINDENT .INDENT 7.0 .TP .B attribute [R] alpn Return ALPN identifier negotiated in this connection. .UNINDENT .INDENT 7.0 .TP .B attribute [R] 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. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class Nghttpx::Request Object to represent request from client. The modification to Request object is allowed only in request phase hook. .INDENT 7.0 .TP .B attribute [R] http_version_major Return HTTP major version. .UNINDENT .INDENT 7.0 .TP .B attribute [R] http_version_minor Return HTTP minor version. .UNINDENT .INDENT 7.0 .TP .B attribute [R/W] method HTTP method. On assignment, copy of given value is assigned. We don\(aqt accept arbitrary method name. We will document them later, but well known methods, like GET, PUT and POST, are all supported. .UNINDENT .INDENT 7.0 .TP .B attribute [R/W] authority Authority (i.e., example.org), including optional port component . On assignment, copy of given value is assigned. .UNINDENT .INDENT 7.0 .TP .B attribute [R/W] scheme Scheme (i.e., http, https). On assignment, copy of given value is assigned. .UNINDENT .INDENT 7.0 .TP .B attribute [R/W] 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 \fI\%https://tools.ietf.org/html/rfc3986#section\-2.3\fP), and resolves \(dq..\(dq and \(dq.\(dq. But it may leave characters which should be percent\-encoded as is. So be careful when comparing path against desired string. .UNINDENT .INDENT 7.0 .TP .B attribute [R] 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 \fI\%Nghttpx::Request#add_header\fP or \fI\%Nghttpx::Request#set_header\fP to change request header fields. .UNINDENT .INDENT 7.0 .TP .B 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. .UNINDENT .INDENT 7.0 .TP .B 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. .UNINDENT .INDENT 7.0 .TP .B clear_headers() Clear all existing request header fields. .UNINDENT .INDENT 7.0 .TP .B push(uri) Initiate to push resource identified by \fIuri\fP\&. Only HTTP/2 protocol supports this feature. For the other protocols, this method is noop. \fIuri\fP 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. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class Nghttpx::Response Object to represent response from backend server. .INDENT 7.0 .TP .B attribute [R] http_version_major Return HTTP major version. .UNINDENT .INDENT 7.0 .TP .B attribute [R] http_version_minor Return HTTP minor version. .UNINDENT .INDENT 7.0 .TP .B attribute [R/W] 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. .UNINDENT .INDENT 7.0 .TP .B attribute [R] 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 \fI\%Nghttpx::Response#add_header\fP or \fI\%Nghttpx::Response#set_header\fP to change response header fields. .UNINDENT .INDENT 7.0 .TP .B 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. .UNINDENT .INDENT 7.0 .TP .B 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. .UNINDENT .INDENT 7.0 .TP .B clear_headers() Clear all existing response header fields. .UNINDENT .INDENT 7.0 .TP .B return(body) Return custom response \fIbody\fP 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 \fI\%Nghttpx::Response#status\fP\&. If status code is not set, 200 is used. To set response header fields, \fI\%Nghttpx::Response#add_header\fP and \fI\%Nghttpx::Response#set_header\fP\&. 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 \fI\%Nghttpx::Response#clear_headers\fP 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. .UNINDENT .INDENT 7.0 .TP .B send_info(status, headers) Send non\-final (informational) response to a client. \fIstatus\fP must be in the range [100, 199], inclusive. \fIheaders\fP 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 \fI\%Nghttpx::Response#return\fP is called. This method can be called multiple times. It cannot be called after \fI\%Nghttpx::Response#return\fP is called. .UNINDENT .UNINDENT .SS MRUBY EXAMPLES .sp Modify request path: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C class App def on_req(env) env.req.path = \(dq/apps#{env.req.path}\(dq end end App.new .ft P .fi .UNINDENT .UNINDENT .sp Don\(aqt forget to instantiate and evaluate object at the last line. .sp Restrict permission of viewing a content to a specific client addresses: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C class App def on_req(env) allowed_clients = [\(dq127.0.0.1\(dq, \(dq::1\(dq] if env.req.path.start_with?(\(dq/log/\(dq) && !allowed_clients.include?(env.remote_addr) then env.resp.status = 404 env.resp.return \(dqpermission denied\(dq end end end App.new .ft P .fi .UNINDENT .UNINDENT .SH API ENDPOINTS .sp 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 \fI\%\-\-frontend\fP option with \(dqapi\(dq parameter. All requests which come from this frontend address, will be treated as API request. .sp The response is normally JSON dictionary, and at least includes the following keys: .INDENT 0.0 .TP .B status The status of the request processing. The following values are defined: .INDENT 7.0 .TP .B Success The request was successful. .TP .B Failure The request was failed. No change has been made. .UNINDENT .TP .B code HTTP status code .UNINDENT .sp Additionally, depending on the API endpoint, \fBdata\fP key may be present, and its value contains the API endpoint specific data. .sp We wrote \(dqnormally\(dq, 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). .sp The following section describes available API endpoints. .SS POST /api/v1beta1/backendconfig .sp 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 \fI\%FILES\fP section. The line separator inside the request body must be single LF (0x0A). Currently, only \fI\%backend\fP 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 \fI\%backend\fP option is found in request body, the current set of backend is replaced with the \fI\%backend\fP option\(aqs default value, which is \fB127.0.0.1,80\fP\&. .sp 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. .sp The one limitation is that only numeric IP address is allowed in \fI\%backend\fP in request body unless \(dqdns\(dq parameter is used while non numeric hostname is allowed in command\-line or configuration file is read using \fI\%\-\-conf\fP\&. .SS GET /api/v1beta1/configrevision .sp 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. .sp This API returns response including \fBdata\fP key. Its value is JSON object, and it contains at least the following key: .INDENT 0.0 .TP .B configRevision The configuration revision of the current nghttpx .UNINDENT .SH SEE ALSO .sp \fBnghttp(1)\fP, \fBnghttpd(1)\fP, \fBh2load(1)\fP .SH AUTHOR Tatsuhiro Tsujikawa .SH COPYRIGHT 2012, 2015, 2016, Tatsuhiro Tsujikawa .\" Generated by docutils manpage writer. . man/man1/h2load.1000064400000036656147633146710007442 0ustar00.\" Man page generated from reStructuredText. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "H2LOAD" "1" "Apr 04, 2024" "1.61.0" "nghttp2" .SH NAME h2load \- HTTP/2 benchmarking tool .SH SYNOPSIS .sp \fBh2load\fP [OPTIONS]... [URI]... .SH DESCRIPTION .sp benchmarking tool for HTTP/2 server .INDENT 0.0 .TP .B Specify URI to access. Multiple URIs can be specified. URIs are used in this order for each client. All URIs are used, then first URI is used and then 2nd URI, and so on. The scheme, host and port in the subsequent URIs, if present, are ignored. Those in the first URI are used solely. Definition of a base URI overrides all scheme, host or port values. .UNINDENT .SH OPTIONS .INDENT 0.0 .TP .B \-n, \-\-requests= Number of requests across all clients. If it is used with \fI\%\-\-timing\-script\-file\fP option, this option specifies the number of requests each client performs rather than the number of requests across all clients. This option is ignored if timing\-based benchmarking is enabled (see \fI\%\-\-duration\fP option). .sp Default: \fB1\fP .UNINDENT .INDENT 0.0 .TP .B \-c, \-\-clients= Number of concurrent clients. With \fI\%\-r\fP option, this specifies the maximum number of connections to be made. .sp Default: \fB1\fP .UNINDENT .INDENT 0.0 .TP .B \-t, \-\-threads= Number of native threads. .sp Default: \fB1\fP .UNINDENT .INDENT 0.0 .TP .B \-i, \-\-input\-file= Path of a file with multiple URIs are separated by EOLs. This option will disable URIs getting from command\-line. If \(aq\-\(aq is given as , URIs will be read from stdin. URIs are used in this order for each client. All URIs are used, then first URI is used and then 2nd URI, and so on. The scheme, host and port in the subsequent URIs, if present, are ignored. Those in the first URI are used solely. Definition of a base URI overrides all scheme, host or port values. .UNINDENT .INDENT 0.0 .TP .B \-m, \-\-max\-concurrent\-streams= Max concurrent streams to issue per session. When http/1.1 is used, this specifies the number of HTTP pipelining requests in\-flight. .sp Default: \fB1\fP .UNINDENT .INDENT 0.0 .TP .B \-f, \-\-max\-frame\-size= Maximum frame size that the local endpoint is willing to receive. .sp Default: \fB16K\fP .UNINDENT .INDENT 0.0 .TP .B \-w, \-\-window\-bits= Sets the stream level initial window size to (2**)\-1. For QUIC, is capped to 26 (roughly 64MiB). .sp Default: \fB30\fP .UNINDENT .INDENT 0.0 .TP .B \-W, \-\-connection\-window\-bits= Sets the connection level initial window size to (2**)\-1. .sp Default: \fB30\fP .UNINDENT .INDENT 0.0 .TP .B \-H, \-\-header=
Add/Override a header to the requests. .UNINDENT .INDENT 0.0 .TP .B \-\-ciphers= Set allowed cipher list for TLSv1.2 or earlier. The format of the string is described in OpenSSL ciphers(1). .sp Default: \fBECDHE\-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\fP .UNINDENT .INDENT 0.0 .TP .B \-\-tls13\-ciphers= Set allowed cipher list for TLSv1.3. The format of the string is described in OpenSSL ciphers(1). .sp Default: \fBTLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_CCM_SHA256\fP .UNINDENT .INDENT 0.0 .TP .B \-p, \-\-no\-tls\-proto= Specify ALPN identifier of the protocol to be used when accessing http URI without SSL/TLS. Available protocols: h2c and http/1.1 .sp Default: \fBh2c\fP .UNINDENT .INDENT 0.0 .TP .B \-d, \-\-data= Post FILE to server. The request method is changed to POST. For http/1.1 connection, if \fI\%\-d\fP is used, the maximum number of in\-flight pipelined requests is set to 1. .UNINDENT .INDENT 0.0 .TP .B \-r, \-\-rate= Specifies the fixed rate at which connections are created. The rate must be a positive integer, representing the number of connections to be made per rate period. The maximum number of connections to be made is given in \fI\%\-c\fP option. This rate will be distributed among threads as evenly as possible. For example, with \fI\%\-t\fP2 and \fI\%\-r\fP4, each thread gets 2 connections per period. When the rate is 0, the program will run as it normally does, creating connections at whatever variable rate it wants. The default value for this option is 0. \fI\%\-r\fP and \fI\%\-D\fP are mutually exclusive. .UNINDENT .INDENT 0.0 .TP .B \-\-rate\-period= Specifies the time period between creating connections. The period must be a positive number, representing the length of the period in time. This option is ignored if the rate option is not used. The default value for this option is 1s. .UNINDENT .INDENT 0.0 .TP .B \-D, \-\-duration= Specifies the main duration for the measurements in case of timing\-based benchmarking. \fI\%\-D\fP and \fI\%\-r\fP are mutually exclusive. .UNINDENT .INDENT 0.0 .TP .B \-\-warm\-up\-time= Specifies the time period before starting the actual measurements, in case of timing\-based benchmarking. Needs to provided along with \fI\%\-D\fP option. .UNINDENT .INDENT 0.0 .TP .B \-T, \-\-connection\-active\-timeout= Specifies the maximum time that h2load is willing to keep a connection open, regardless of the activity on said connection. must be a positive integer, specifying the amount of time to wait. When no timeout value is set (either active or inactive), h2load will keep a connection open indefinitely, waiting for a response. .UNINDENT .INDENT 0.0 .TP .B \-N, \-\-connection\-inactivity\-timeout= Specifies the amount of time that h2load is willing to wait to see activity on a given connection. must be a positive integer, specifying the amount of time to wait. When no timeout value is set (either active or inactive), h2load will keep a connection open indefinitely, waiting for a response. .UNINDENT .INDENT 0.0 .TP .B \-\-timing\-script\-file= Path of a file containing one or more lines separated by EOLs. Each script line is composed of two tab\-separated fields. The first field represents the time offset from the start of execution, expressed as a positive value of milliseconds with microsecond resolution. The second field represents the URI. This option will disable URIs getting from command\-line. If \(aq\-\(aq is given as , script lines will be read from stdin. Script lines are used in order for each client. If \fI\%\-n\fP is given, it must be less than or equal to the number of script lines, larger values are clamped to the number of script lines. If \fI\%\-n\fP is not given, the number of requests will default to the number of script lines. The scheme, host and port defined in the first URI are used solely. Values contained in other URIs, if present, are ignored. Definition of a base URI overrides all scheme, host or port values. \fI\%\-\-timing\-script\-file\fP and \fI\%\-\-rps\fP are mutually exclusive. .UNINDENT .INDENT 0.0 .TP .B \-B, \-\-base\-uri=(|unix:) Specify URI from which the scheme, host and port will be used for all requests. The base URI overrides all values defined either at the command line or inside input files. If argument starts with \(dqunix:\(dq, then the rest of the argument will be treated as UNIX domain socket path. The connection is made through that path instead of TCP. In this case, scheme is inferred from the first URI appeared in the command line or inside input files as usual. .UNINDENT .INDENT 0.0 .TP .B \-\-alpn\-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. .sp Default: \fBh2,h2\-16,h2\-14,http/1.1\fP .UNINDENT .INDENT 0.0 .TP .B \-\-h1 Short hand for \fI\%\-\-alpn\-list\fP=http/1.1 \fI\%\-\-no\-tls\-proto\fP=http/1.1, which effectively force http/1.1 for both http and https URI. .UNINDENT .INDENT 0.0 .TP .B \-\-header\-table\-size= Specify decoder header table size. .sp Default: \fB4K\fP .UNINDENT .INDENT 0.0 .TP .B \-\-encoder\-header\-table\-size= Specify encoder header table size. The decoder (server) 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 server specified. .sp Default: \fB4K\fP .UNINDENT .INDENT 0.0 .TP .B \-\-log\-file= Write per\-request information to a file as tab\-separated columns: start time as microseconds since epoch; HTTP status code; microseconds until end of response. More columns may be added later. Rows are ordered by end\-of\- response time when using one worker thread, but may appear slightly out of order with multiple threads due to buffering. Status code is \-1 for failed streams. .UNINDENT .INDENT 0.0 .TP .B \-\-qlog\-file\-base= Enable qlog output and specify base file name for qlogs. Qlog is emitted for each connection. For a given base name \(dqbase\(dq, each output file name becomes \(dqbase.M.N.sqlog\(dq where M is worker ID and N is client ID (e.g. \(dqbase.0.3.sqlog\(dq). Only effective in QUIC runs. .UNINDENT .INDENT 0.0 .TP .B \-\-connect\-to=[:] Host and port to connect instead of using the authority in . .UNINDENT .INDENT 0.0 .TP .B \-\-rps= Specify request per second for each client. \fI\%\-\-rps\fP and \fI\%\-\-timing\-script\-file\fP are mutually exclusive. .UNINDENT .INDENT 0.0 .TP .B \-\-groups= Specify the supported groups. .sp Default: \fBX25519:P\-256:P\-384:P\-521\fP .UNINDENT .INDENT 0.0 .TP .B \-\-no\-udp\-gso Disable UDP GSO. .UNINDENT .INDENT 0.0 .TP .B \-\-max\-udp\-payload\-size= Specify the maximum outgoing UDP datagram payload size. .UNINDENT .INDENT 0.0 .TP .B \-\-ktls Enable ktls. .UNINDENT .INDENT 0.0 .TP .B \-\-sni= Send in TLS SNI, overriding the host name specified in URI. .UNINDENT .INDENT 0.0 .TP .B \-v, \-\-verbose Output debug information. .UNINDENT .INDENT 0.0 .TP .B \-\-version Display version information and exit. .UNINDENT .INDENT 0.0 .TP .B \-h, \-\-help Display this help and exit. .UNINDENT .sp The argument is an integer and an optional unit (e.g., 10K is 10 * 1024). Units are K, M and G (powers of 1024). .sp The 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. .SH OUTPUT .INDENT 0.0 .TP .B requests .INDENT 7.0 .TP .B total The number of requests h2load was instructed to make. .TP .B started The number of requests h2load has started. .TP .B done The number of requests completed. .TP .B succeeded The number of requests completed successfully. Only HTTP status code 2xx or3xx are considered as success. .TP .B failed The number of requests failed, including HTTP level failures (non\-successful HTTP status code). .TP .B errored The number of requests failed, except for HTTP level failures. This is the subset of the number reported in \fBfailed\fP and most likely the network level failures or stream was reset by RST_STREAM. .TP .B timeout The number of requests whose connection timed out before they were completed. This is the subset of the number reported in \fBerrored\fP\&. .UNINDENT .TP .B status codes The number of status code h2load received. .TP .B traffic .INDENT 7.0 .TP .B total The number of bytes received from the server \(dqon the wire\(dq. If requests were made via TLS, this value is the number of decrypted bytes. .TP .B headers The number of response header bytes from the server without decompression. The \fBspace savings\fP shows efficiency of header compression. Let \fBdecompressed(headers)\fP to the number of bytes used for header fields after decompression. The \fBspace savings\fP is calculated by (1 \- \fBheaders\fP / \fBdecompressed(headers)\fP) * 100. For HTTP/1.1, this is usually 0.00%, since it does not have header compression. For HTTP/2, it shows some insightful numbers. .TP .B data The number of response body bytes received from the server. .UNINDENT .TP .B time for request .INDENT 7.0 .TP .B min The minimum time taken for request and response. .TP .B max The maximum time taken for request and response. .TP .B mean The mean time taken for request and response. .TP .B sd The standard deviation of the time taken for request and response. .TP .B +/\- sd The fraction of the number of requests within standard deviation range (mean +/\- sd) against total number of successful requests. .UNINDENT .TP .B time for connect .INDENT 7.0 .TP .B min The minimum time taken to connect to a server including TLS handshake. .TP .B max The maximum time taken to connect to a server including TLS handshake. .TP .B mean The mean time taken to connect to a server including TLS handshake. .TP .B sd The standard deviation of the time taken to connect to a server. .TP .B +/\- sd The fraction of the number of connections within standard deviation range (mean +/\- sd) against total number of successful connections. .UNINDENT .TP .B time for 1st byte (of (decrypted in case of TLS) application data) .INDENT 7.0 .TP .B min The minimum time taken to get 1st byte from a server. .TP .B max The maximum time taken to get 1st byte from a server. .TP .B mean The mean time taken to get 1st byte from a server. .TP .B sd The standard deviation of the time taken to get 1st byte from a server. .TP .B +/\- sd The fraction of the number of connections within standard deviation range (mean +/\- sd) against total number of successful connections. .UNINDENT .TP .B req/s .INDENT 7.0 .TP .B min The minimum request per second among all clients. .TP .B max The maximum request per second among all clients. .TP .B mean The mean request per second among all clients. .TP .B sd The standard deviation of request per second among all clients. server. .TP .B +/\- sd The fraction of the number of connections within standard deviation range (mean +/\- sd) against total number of successful connections. .UNINDENT .UNINDENT .SH FLOW CONTROL .sp h2load sets large flow control window by default, and effectively disables flow control to avoid under utilization of server performance. To set smaller flow control window, use \fI\%\-w\fP and \fI\%\-W\fP options. For example, use \fB\-w16 \-W16\fP to set default window size described in HTTP/2 protocol specification. .SH SEE ALSO .sp \fBnghttp(1)\fP, \fBnghttpd(1)\fP, \fBnghttpx(1)\fP .SH AUTHOR Tatsuhiro Tsujikawa .SH COPYRIGHT 2012, 2015, 2016, Tatsuhiro Tsujikawa .\" Generated by docutils manpage writer. . man/man1/nghttp.1000064400000021460147633146710007560 0ustar00.\" Man page generated from reStructuredText. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "NGHTTP" "1" "Apr 04, 2024" "1.61.0" "nghttp2" .SH NAME nghttp \- HTTP/2 client .SH SYNOPSIS .sp \fBnghttp\fP [OPTIONS]... ... .SH DESCRIPTION .sp HTTP/2 client .INDENT 0.0 .TP .B Specify URI to access. .UNINDENT .SH OPTIONS .INDENT 0.0 .TP .B \-v, \-\-verbose Print debug information such as reception and transmission of frames and name/value pairs. Specifying this option multiple times increases verbosity. .UNINDENT .INDENT 0.0 .TP .B \-n, \-\-null\-out Discard downloaded data. .UNINDENT .INDENT 0.0 .TP .B \-O, \-\-remote\-name Save download data in the current directory. The filename is derived from URI. If URI ends with \(aq\fI/\fP\(aq, \(aqindex.html\(aq is used as a filename. Not implemented yet. .UNINDENT .INDENT 0.0 .TP .B \-t, \-\-timeout= Timeout each request after . Set 0 to disable timeout. .UNINDENT .INDENT 0.0 .TP .B \-w, \-\-window\-bits= Sets the stream level initial window size to 2**\-1. .UNINDENT .INDENT 0.0 .TP .B \-W, \-\-connection\-window\-bits= Sets the connection level initial window size to 2**\-1. .UNINDENT .INDENT 0.0 .TP .B \-a, \-\-get\-assets Download assets such as stylesheets, images and script files linked from the downloaded resource. Only links whose origins are the same with the linking resource will be downloaded. nghttp prioritizes resources using HTTP/2 dependency based priority. The priority order, from highest to lowest, is html itself, css, javascript and images. .UNINDENT .INDENT 0.0 .TP .B \-s, \-\-stat Print statistics. .UNINDENT .INDENT 0.0 .TP .B \-H, \-\-header=
Add a header to the requests. Example: \fI\%\-H\fP\(aq:method: PUT\(aq .UNINDENT .INDENT 0.0 .TP .B \-\-trailer=
Add a trailer header to the requests.
must not include pseudo header field (header field name starting with \(aq:\(aq). To send trailer, one must use \fI\%\-d\fP option to send request body. Example: \fI\%\-\-trailer\fP \(aqfoo: bar\(aq. .UNINDENT .INDENT 0.0 .TP .B \-\-cert= Use the specified client certificate file. The file must be in PEM format. .UNINDENT .INDENT 0.0 .TP .B \-\-key= Use the client private key file. The file must be in PEM format. .UNINDENT .INDENT 0.0 .TP .B \-d, \-\-data= Post FILE to server. If \(aq\-\(aq is given, data will be read from stdin. .UNINDENT .INDENT 0.0 .TP .B \-m, \-\-multiply= Request each URI times. By default, same URI is not requested twice. This option disables it too. .UNINDENT .INDENT 0.0 .TP .B \-u, \-\-upgrade Perform HTTP Upgrade for HTTP/2. This option is ignored if the request URI has https scheme. If \fI\%\-d\fP is used, the HTTP upgrade request is performed with OPTIONS method. .UNINDENT .INDENT 0.0 .TP .B \-p, \-\-weight= Sets weight of given URI. This option can be used multiple times, and N\-th \fI\%\-p\fP option sets weight of N\-th URI in the command line. If the number of \fI\%\-p\fP option is less than the number of URI, the last \fI\%\-p\fP option value is repeated. If there is no \fI\%\-p\fP option, default weight, 16, is assumed. The valid value range is [1, 256], inclusive. .UNINDENT .INDENT 0.0 .TP .B \-M, \-\-peer\-max\-concurrent\-streams= Use as SETTINGS_MAX_CONCURRENT_STREAMS value of remote endpoint as if it is received in SETTINGS frame. .sp Default: \fB100\fP .UNINDENT .INDENT 0.0 .TP .B \-c, \-\-header\-table\-size= Specify decoder header table size. If this option is used multiple times, and the minimum value among the given values except for last one is strictly less than the last value, that minimum value is set in SETTINGS frame payload before the last value, to simulate multiple header table size change. .UNINDENT .INDENT 0.0 .TP .B \-\-encoder\-header\-table\-size= Specify encoder header table size. The decoder (server) 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 server specified. .UNINDENT .INDENT 0.0 .TP .B \-b, \-\-padding= Add at most bytes to a frame payload as padding. Specify 0 to disable padding. .UNINDENT .INDENT 0.0 .TP .B \-r, \-\-har= Output HTTP transactions in HAR format. If \(aq\-\(aq is given, data is written to stdout. .UNINDENT .INDENT 0.0 .TP .B \-\-color Force colored log output. .UNINDENT .INDENT 0.0 .TP .B \-\-continuation Send large header to test CONTINUATION. .UNINDENT .INDENT 0.0 .TP .B \-\-no\-content\-length Don\(aqt send content\-length header field. .UNINDENT .INDENT 0.0 .TP .B \-\-no\-dep Don\(aqt send dependency based priority hint to server. .UNINDENT .INDENT 0.0 .TP .B \-\-hexdump Display the incoming traffic in hexadecimal (Canonical hex+ASCII display). If SSL/TLS is used, decrypted data are used. .UNINDENT .INDENT 0.0 .TP .B \-\-no\-push Disable server push. .UNINDENT .INDENT 0.0 .TP .B \-\-max\-concurrent\-streams= The number of concurrent pushed streams this client accepts. .UNINDENT .INDENT 0.0 .TP .B \-\-expect\-continue Perform an Expect/Continue handshake: wait to send DATA (up to a short timeout) until the server sends a 100 Continue interim response. This option is ignored unless combined with the \fI\%\-d\fP option. .UNINDENT .INDENT 0.0 .TP .B \-y, \-\-no\-verify\-peer Suppress warning on server certificate verification failure. .UNINDENT .INDENT 0.0 .TP .B \-\-ktls Enable ktls. .UNINDENT .INDENT 0.0 .TP .B \-\-no\-rfc7540\-pri Disable RFC7540 priorities. .UNINDENT .INDENT 0.0 .TP .B \-\-version Display version information and exit. .UNINDENT .INDENT 0.0 .TP .B \-h, \-\-help Display this help and exit. .UNINDENT .sp The argument is an integer and an optional unit (e.g., 10K is 10 * 1024). Units are K, M and G (powers of 1024). .sp The 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. .SH DEPENDENCY BASED PRIORITY .sp nghttp sends priority hints to server by default unless \fI\%\-\-no\-dep\fP is used. nghttp mimics the way Firefox employs to manages dependency using idle streams. We follows the behaviour of Firefox Nightly as of April, 2015, and nghttp\(aqs behaviour is very static and could be different from Firefox in detail. But reproducing the same behaviour of Firefox is not our goal. The goal is provide the easy way to test out the dependency priority in server implementation. .sp When connection is established, nghttp sends 5 PRIORITY frames to idle streams 3, 5, 7, 9 and 11 to create \(dqanchor\(dq nodes in dependency tree: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C +\-\-\-\-\-+ |id=0 | +\-\-\-\-\-+ ^ ^ ^ w=201 / | \e w=1 / | \e / w=101| \e +\-\-\-\-\-+ +\-\-\-\-\-+ +\-\-\-\-\-+ |id=3 | |id=5 | |id=7 | +\-\-\-\-\-+ +\-\-\-\-\-+ +\-\-\-\-\-+ ^ ^ w=1 | w=1 | | | +\-\-\-\-\-+ +\-\-\-\-\-+ |id=11| |id=9 | +\-\-\-\-\-+ +\-\-\-\-\-+ .ft P .fi .UNINDENT .UNINDENT .sp In the above figure, \fBid\fP means stream ID, and \fBw\fP means weight. The stream 0 is non\-existence stream, and forms the root of the tree. The stream 7 and 9 are not used for now. .sp The URIs given in the command\-line depend on stream 11 with the weight given in \fI\%\-p\fP option, which defaults to 16. .sp If \fI\%\-a\fP option is used, nghttp parses the resource pointed by URI given in command\-line as html, and extracts resource links from it. When requesting those resources, nghttp uses dependency according to its resource type. .sp For CSS, and Javascript files inside \(dqhead\(dq element, they depend on stream 3 with the weight 2. The Javascript files outside \(dqhead\(dq element depend on stream 5 with the weight 2. The mages depend on stream 11 with the weight 12. The other resources (e.g., icon) depend on stream 11 with the weight 2. .SH SEE ALSO .sp \fBnghttpd(1)\fP, \fBnghttpx(1)\fP, \fBh2load(1)\fP .SH AUTHOR Tatsuhiro Tsujikawa .SH COPYRIGHT 2012, 2015, 2016, Tatsuhiro Tsujikawa .\" Generated by docutils manpage writer. . man/man1/nghttpd.1000064400000012627147633146710007731 0ustar00.\" Man page generated from reStructuredText. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "NGHTTPD" "1" "Apr 04, 2024" "1.61.0" "nghttp2" .SH NAME nghttpd \- HTTP/2 server .SH SYNOPSIS .sp \fBnghttpd\fP [OPTION]... [ ] .SH DESCRIPTION .sp HTTP/2 server .INDENT 0.0 .TP .B Specify listening port number. .UNINDENT .INDENT 0.0 .TP .B Set path to server\(aqs private key. Required unless \fI\%\-\-no\-tls\fP is specified. .UNINDENT .INDENT 0.0 .TP .B Set path to server\(aqs certificate. Required unless \fI\%\-\-no\-tls\fP is specified. .UNINDENT .SH OPTIONS .INDENT 0.0 .TP .B \-a, \-\-address= The address to bind to. If not specified the default IP address determined by getaddrinfo is used. .UNINDENT .INDENT 0.0 .TP .B \-D, \-\-daemon Run in a background. If \fI\%\-D\fP is used, the current working directory is changed to \(aq\fI/\fP\(aq. Therefore if this option is used, \fI\%\-d\fP option must be specified. .UNINDENT .INDENT 0.0 .TP .B \-V, \-\-verify\-client The server sends a client certificate request. If the client did not return a certificate, the handshake is terminated. Currently, this option just requests a client certificate and does not verify it. .UNINDENT .INDENT 0.0 .TP .B \-d, \-\-htdocs= Specify document root. If this option is not specified, the document root is the current working directory. .UNINDENT .INDENT 0.0 .TP .B \-v, \-\-verbose Print debug information such as reception/ transmission of frames and name/value pairs. .UNINDENT .INDENT 0.0 .TP .B \-\-no\-tls Disable SSL/TLS. .UNINDENT .INDENT 0.0 .TP .B \-c, \-\-header\-table\-size= Specify decoder header table size. .UNINDENT .INDENT 0.0 .TP .B \-\-encoder\-header\-table\-size= Specify encoder header table size. 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. .UNINDENT .INDENT 0.0 .TP .B \-\-color Force colored log output. .UNINDENT .INDENT 0.0 .TP .B \-p, \-\-push== Push resources s when is requested. This option can be used repeatedly to specify multiple push configurations. and s are relative to document root. See \fI\%\-\-htdocs\fP option. Example: \fI\%\-p\fP/=/foo.png \fI\%\-p\fP/doc=/bar.css .UNINDENT .INDENT 0.0 .TP .B \-b, \-\-padding= Add at most bytes to a frame payload as padding. Specify 0 to disable padding. .UNINDENT .INDENT 0.0 .TP .B \-m, \-\-max\-concurrent\-streams= Set the maximum number of the concurrent streams in one HTTP/2 session. .sp Default: \fB100\fP .UNINDENT .INDENT 0.0 .TP .B \-n, \-\-workers= Set the number of worker threads. .sp Default: \fB1\fP .UNINDENT .INDENT 0.0 .TP .B \-e, \-\-error\-gzip Make error response gzipped. .UNINDENT .INDENT 0.0 .TP .B \-w, \-\-window\-bits= Sets the stream level initial window size to 2**\-1. .UNINDENT .INDENT 0.0 .TP .B \-W, \-\-connection\-window\-bits= Sets the connection level initial window size to 2**\-1. .UNINDENT .INDENT 0.0 .TP .B \-\-dh\-param\-file= Path to file that contains DH parameters in PEM format. Without this option, DHE cipher suites are not available. .UNINDENT .INDENT 0.0 .TP .B \-\-early\-response Start sending response when request HEADERS is received, rather than complete request is received. .UNINDENT .INDENT 0.0 .TP .B \-\-trailer=
Add a trailer header to a response.
must not include pseudo header field (header field name starting with \(aq:\(aq). The trailer is sent only if a response has body part. Example: \fI\%\-\-trailer\fP \(aqfoo: bar\(aq. .UNINDENT .INDENT 0.0 .TP .B \-\-hexdump Display the incoming traffic in hexadecimal (Canonical hex+ASCII display). If SSL/TLS is used, decrypted data are used. .UNINDENT .INDENT 0.0 .TP .B \-\-echo\-upload Send back uploaded content if method is POST or PUT. .UNINDENT .INDENT 0.0 .TP .B \-\-mime\-types\-file= Path to file that contains MIME media types and the extensions that represent them. .sp Default: \fB/etc/mime.types\fP .UNINDENT .INDENT 0.0 .TP .B \-\-no\-content\-length Don\(aqt send content\-length header field. .UNINDENT .INDENT 0.0 .TP .B \-\-ktls Enable ktls. .UNINDENT .INDENT 0.0 .TP .B \-\-no\-rfc7540\-pri Disable RFC7540 priorities. .UNINDENT .INDENT 0.0 .TP .B \-\-version Display version information and exit. .UNINDENT .INDENT 0.0 .TP .B \-h, \-\-help Display this help and exit. .UNINDENT .sp The argument is an integer and an optional unit (e.g., 10K is 10 * 1024). Units are K, M and G (powers of 1024). .SH SEE ALSO .sp \fBnghttp(1)\fP, \fBnghttpx(1)\fP, \fBh2load(1)\fP .SH AUTHOR Tatsuhiro Tsujikawa .SH COPYRIGHT 2012, 2015, 2016, Tatsuhiro Tsujikawa .\" Generated by docutils manpage writer. . doc/nghttp2/README.rst000064400000140643147633146710010412 0ustar00nghttp2 - HTTP/2 C Library ========================== This is an implementation of the Hypertext Transfer Protocol version 2 in C. The framing layer of HTTP/2 is implemented as a reusable C library. On top of that, we have implemented an HTTP/2 client, server and proxy. We have also developed load test and benchmarking tools for HTTP/2. An HPACK encoder and decoder are available as a public API. Development Status ------------------ nghttp2 was originally developed based on `RFC 7540 `_ HTTP/2 and `RFC 7541 `_ HPACK - Header Compression for HTTP/2. Now we are updating our code to implement `RFC 9113 `_. The nghttp2 code base was forked from the spdylay (https://github.com/tatsuhiro-t/spdylay) project. Public Test Server ------------------ The following endpoints are available to try out our nghttp2 implementation. * https://nghttp2.org/ (TLS + ALPN and HTTP/3) This endpoint supports ``h2``, ``h2-16``, ``h2-14``, and ``http/1.1`` via ALPN and requires TLSv1.2 for HTTP/2 connection. It also supports HTTP/3. * http://nghttp2.org/ (HTTP Upgrade and HTTP/2 Direct) ``h2c`` and ``http/1.1``. Requirements ------------ The following package is required to build the libnghttp2 library: * pkg-config >= 0.20 To build the documentation, you need to install: * sphinx (http://sphinx-doc.org/) If you need libnghttp2 (C library) only, then the above packages are all you need. Use ``--enable-lib-only`` to ensure that only libnghttp2 is built. This avoids potential build error related to building bundled applications. To build and run the application programs (``nghttp``, ``nghttpd``, ``nghttpx`` and ``h2load``) in the ``src`` directory, the following packages are required: * OpenSSL >= 1.1.1; or LibreSSL >= 3.8.1; or aws-lc >= 1.19.0; or BoringSSL * libev >= 4.11 * zlib >= 1.2.3 * libc-ares >= 1.7.5 To enable ``-a`` option (getting linked assets from the downloaded resource) in ``nghttp``, the following package is required: * libxml2 >= 2.6.26 To enable systemd support in nghttpx, the following package is required: * libsystemd-dev >= 209 The HPACK tools require the following package: * jansson >= 2.5 To build sources under the examples directory, libevent is required: * libevent-openssl >= 2.0.8 To mitigate heap fragmentation in long running server programs (``nghttpd`` and ``nghttpx``), jemalloc is recommended: * jemalloc .. note:: Alpine Linux currently does not support malloc replacement due to musl limitations. See details in issue `#762 `_. For BoringSSL or aws-lc build, to enable :rfc:`8879` TLS Certificate Compression in applications, the following library is required: * libbrotli-dev >= 1.0.9 To enable mruby support for nghttpx, `mruby `_ is required. We need to build mruby with C++ ABI explicitly turned on, and probably need other mrgems, mruby is managed by git submodule under third-party/mruby directory. Currently, mruby support for nghttpx is disabled by default. To enable mruby support, use ``--with-mruby`` configure option. Note that at the time of this writing, libmruby-dev and mruby packages in Debian/Ubuntu are not usable for nghttp2, since they do not enable C++ ABI. To build mruby, the following packages are required: * ruby * bison nghttpx supports `neverbleed `_, privilege separation engine for OpenSSL. In short, it minimizes the risk of private key leakage when serious bug like Heartbleed is exploited. The neverbleed is disabled by default. To enable it, use ``--with-neverbleed`` configure option. To enable the experimental HTTP/3 support for h2load and nghttpx, the following libraries are required: * `OpenSSL with QUIC support `_; or LibreSSL (does not support 0RTT); or aws-lc; or `BoringSSL `_ (commit fae0964b3d44e94ca2a2d21f86e61dabe683d130) * `ngtcp2 `_ >= 1.4.0 * `nghttp3 `_ >= 1.1.0 Use ``--enable-http3`` configure option to enable HTTP/3 feature for h2load and nghttpx. In order to build optional eBPF program to direct an incoming QUIC UDP datagram to a correct socket for nghttpx, the following libraries are required: * libbpf-dev >= 0.7.0 Use ``--with-libbpf`` configure option to build eBPF program. libelf-dev is needed to build libbpf. For Ubuntu 20.04, you can build libbpf from `the source code `_. nghttpx requires eBPF program for reloading its configuration and hot swapping its executable. Compiling libnghttp2 C source code requires a C99 compiler. gcc 4.8 is known to be adequate. In order to compile the C++ source code, gcc >= 6.0 or clang >= 6.0 is required. C++ source code requires C++14 language features. .. note:: To enable mruby support in nghttpx, and use ``--with-mruby`` configure option. .. note:: Mac OS X users may need the ``--disable-threads`` configure option to disable multi-threading in nghttpd, nghttpx and h2load to prevent them from crashing. A patch is welcome to make multi threading work on Mac OS X platform. .. note:: To compile the associated applications (nghttp, nghttpd, nghttpx and h2load), you must use the ``--enable-app`` configure option and ensure that the specified requirements above are met. Normally, configure script checks required dependencies to build these applications, and enable ``--enable-app`` automatically, so you don't have to use it explicitly. But if you found that applications were not built, then using ``--enable-app`` may find that cause, such as the missing dependency. .. note:: In order to detect third party libraries, pkg-config is used (however we don't use pkg-config for some libraries (e.g., libev)). By default, pkg-config searches ``*.pc`` file in the standard locations (e.g., /usr/lib/pkgconfig). If it is necessary to use ``*.pc`` file in the custom location, specify paths to ``PKG_CONFIG_PATH`` environment variable, and pass it to configure script, like so: .. code-block:: text $ ./configure PKG_CONFIG_PATH=/path/to/pkgconfig For pkg-config managed libraries, ``*_CFLAG`` and ``*_LIBS`` environment variables are defined (e.g., ``OPENSSL_CFLAGS``, ``OPENSSL_LIBS``). Specifying non-empty string to these variables completely overrides pkg-config. In other words, if they are specified, pkg-config is not used for detection, and user is responsible to specify the correct values to these variables. For complete list of these variables, run ``./configure -h``. If you are using Ubuntu 22.04 LTS, run the following to install the required packages: .. code-block:: text sudo apt-get install g++ clang make binutils autoconf automake \ autotools-dev libtool pkg-config \ zlib1g-dev libssl-dev libxml2-dev libev-dev \ libevent-dev libjansson-dev \ libc-ares-dev libjemalloc-dev libsystemd-dev \ ruby-dev bison libelf-dev Building nghttp2 from release tar archive ----------------------------------------- The nghttp2 project regularly releases tar archives which includes nghttp2 source code, and generated build files. They can be downloaded from `Releases `_ page. Building nghttp2 from git requires autotools development packages. Building from tar archives does not require them, and thus it is much easier. The usual build step is as follows: .. code-block:: text $ tar xf nghttp2-X.Y.Z.tar.bz2 $ cd nghttp2-X.Y.Z $ ./configure $ make Building from git ----------------- Building from git is easy, but please be sure that at least autoconf 2.68 is used: .. code-block:: text $ git submodule update --init $ autoreconf -i $ automake $ autoconf $ ./configure $ make Notes for building on Windows (MSVC) ------------------------------------ The easiest way to build native Windows nghttp2 dll is use `cmake `_. The free version of `Visual C++ Build Tools `_ works fine. 1. Install cmake for windows 2. Open "Visual C++ ... Native Build Tool Command Prompt", and inside nghttp2 directly, run ``cmake``. 3. Then run ``cmake --build`` to build library. 4. nghttp2.dll, nghttp2.lib, nghttp2.exp are placed under lib directory. Note that the above steps most likely produce nghttp2 library only. No bundled applications are compiled. Notes for building on Windows (Mingw/Cygwin) -------------------------------------------- Under Mingw environment, you can only compile the library, it's ``libnghttp2-X.dll`` and ``libnghttp2.a``. If you want to compile the applications(``h2load``, ``nghttp``, ``nghttpx``, ``nghttpd``), you need to use the Cygwin environment. Under Cygwin environment, to compile the applications you need to compile and install the libev first. Secondly, you need to undefine the macro ``__STRICT_ANSI__``, if you not, the functions ``fdopen``, ``fileno`` and ``strptime`` will not available. the sample command like this: .. code-block:: text $ export CFLAGS="-U__STRICT_ANSI__ -I$libev_PREFIX/include -L$libev_PREFIX/lib" $ export CXXFLAGS=$CFLAGS $ ./configure $ make If you want to compile the applications under ``examples/``, you need to remove or rename the ``event.h`` from libev's installation, because it conflicts with libevent's installation. Notes for installation on Linux systems -------------------------------------------- After installing nghttp2 tool suite with ``make install`` one might experience a similar error: .. code-block:: text nghttpx: error while loading shared libraries: libnghttp2.so.14: cannot open shared object file: No such file or directory This means that the tool is unable to locate the ``libnghttp2.so`` shared library. To update the shared library cache run ``sudo ldconfig``. Building the documentation -------------------------- .. note:: Documentation is still incomplete. To build the documentation, run: .. code-block:: text $ make html The documents will be generated under ``doc/manual/html/``. The generated documents will not be installed with ``make install``. The online documentation is available at https://nghttp2.org/documentation/ Build HTTP/3 enabled h2load and nghttpx --------------------------------------- To build h2load and nghttpx with HTTP/3 feature enabled, run the configure script with ``--enable-http3``. For nghttpx to reload configurations and swapping its executable while gracefully terminating old worker processes, eBPF is required. Run the configure script with ``--enable-http3 --with-libbpf`` to build eBPF program. The QUIC keying material must be set with ``--frontend-quic-secret-file`` in order to keep the existing connections alive during reload. The detailed steps to build HTTP/3 enabled h2load and nghttpx follow. Build aws-lc: .. code-block:: text $ git clone --depth 1 -b v1.23.0 https://github.com/aws/aws-lc $ cd aws-lc $ cmake -B build -DDISABLE_GO=ON --install-prefix=$PWD/opt $ make -j$(nproc) -C build $ cmake --install build $ cd .. Build nghttp3: .. code-block:: text $ git clone --depth 1 -b v1.2.0 https://github.com/ngtcp2/nghttp3 $ cd nghttp3 $ git submodule update --init --depth 1 $ autoreconf -i $ ./configure --prefix=$PWD/build --enable-lib-only $ make -j$(nproc) $ make install $ cd .. Build ngtcp2: .. code-block:: text $ git clone --depth 1 -b v1.4.0 https://github.com/ngtcp2/ngtcp2 $ cd ngtcp2 $ git submodule update --init --depth 1 $ autoreconf -i $ ./configure --prefix=$PWD/build --enable-lib-only --with-boringssl \ BORINGSSL_CFLAGS="-I$PWD/../aws-lc/opt/include" \ BORINGSSL_LIBS="-L$PWD/../aws-lc/opt/lib -lssl -lcrypto" $ make -j$(nproc) $ make install $ cd .. If your Linux distribution does not have libbpf-dev >= 0.7.0, build from source: .. code-block:: text $ git clone --depth 1 -b v1.3.0 https://github.com/libbpf/libbpf $ cd libbpf $ PREFIX=$PWD/build make -C src install $ cd .. Build nghttp2: .. code-block:: text $ git clone https://github.com/nghttp2/nghttp2 $ cd nghttp2 $ git submodule update --init $ autoreconf -i $ ./configure --with-mruby --enable-http3 --with-libbpf \ CC=clang-15 CXX=clang++-15 \ PKG_CONFIG_PATH="$PWD/../aws-lc/opt/lib/pkgconfig:$PWD/../nghttp3/build/lib/pkgconfig:$PWD/../ngtcp2/build/lib/pkgconfig:$PWD/../libbpf/build/lib64/pkgconfig" \ LDFLAGS="$LDFLAGS -Wl,-rpath,$PWD/../aws-lc/opt/lib -Wl,-rpath,$PWD/../libbpf/build/lib64" $ make -j$(nproc) The eBPF program ``reuseport_kern.o`` should be found under bpf directory. Pass ``--quic-bpf-program-file=bpf/reuseport_kern.o`` option to nghttpx to load it. See also `HTTP/3 section in nghttpx - HTTP/2 proxy - HOW-TO `_. Unit tests ---------- Unit tests are done by simply running ``make check``. Integration tests ----------------- We have the integration tests for the nghttpx proxy server. The tests are written in the `Go programming language `_ and uses its testing framework. We depend on the following libraries: * golang.org/x/net/http2 * golang.org/x/net/websocket * https://github.com/tatsuhiro-t/go-nghttp2 Go modules will download these dependencies automatically. To run the tests, run the following command under ``integration-tests`` directory: .. code-block:: text $ make it Inside the tests, we use port 3009 to run the test subject server. Migration from v0.7.15 or earlier --------------------------------- nghttp2 v1.0.0 introduced several backward incompatible changes. In this section, we describe these changes and how to migrate to v1.0.0. ALPN protocol ID is now ``h2`` and ``h2c`` ++++++++++++++++++++++++++++++++++++++++++ Previously we announced ``h2-14`` and ``h2c-14``. v1.0.0 implements final protocol version, and we changed ALPN ID to ``h2`` and ``h2c``. The macros ``NGHTTP2_PROTO_VERSION_ID``, ``NGHTTP2_PROTO_VERSION_ID_LEN``, ``NGHTTP2_CLEARTEXT_PROTO_VERSION_ID``, and ``NGHTTP2_CLEARTEXT_PROTO_VERSION_ID_LEN`` have been updated to reflect this change. Basically, existing applications do not have to do anything, just recompiling is enough for this change. Use word "client magic" where we use "client connection preface" ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ We use "client connection preface" to mean first 24 bytes of client connection preface. This is technically not correct, since client connection preface is composed of 24 bytes client magic byte string followed by SETTINGS frame. For clarification, we call "client magic" for this 24 bytes byte string and updated API. * ``NGHTTP2_CLIENT_CONNECTION_PREFACE`` was replaced with ``NGHTTP2_CLIENT_MAGIC``. * ``NGHTTP2_CLIENT_CONNECTION_PREFACE_LEN`` was replaced with ``NGHTTP2_CLIENT_MAGIC_LEN``. * ``NGHTTP2_BAD_PREFACE`` was renamed as ``NGHTTP2_BAD_CLIENT_MAGIC`` The already deprecated ``NGHTTP2_CLIENT_CONNECTION_HEADER`` and ``NGHTTP2_CLIENT_CONNECTION_HEADER_LEN`` were removed. If application uses these macros, just replace old ones with new ones. Since v1.0.0, client magic is sent by library (see next subsection), so client application may just remove these macro use. Client magic is sent by library +++++++++++++++++++++++++++++++ Previously nghttp2 library did not send client magic, which is first 24 bytes byte string of client connection preface, and client applications have to send it by themselves. Since v1.0.0, client magic is sent by library via first call of ``nghttp2_session_send()`` or ``nghttp2_session_mem_send2()``. The client applications which send client magic must remove the relevant code. Remove HTTP Alternative Services (Alt-Svc) related code +++++++++++++++++++++++++++++++++++++++++++++++++++++++ Alt-Svc specification is not finalized yet. To make our API stable, we have decided to remove all Alt-Svc related API from nghttp2. * ``NGHTTP2_EXT_ALTSVC`` was removed. * ``nghttp2_ext_altsvc`` was removed. We have already removed the functionality of Alt-Svc in v0.7 series and they have been essentially noop. The application using these macro and struct, remove those lines. Use nghttp2_error in nghttp2_on_invalid_frame_recv_callback +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Previously ``nghttp2_on_invalid_frame_recv_cb_called`` took the ``error_code``, defined in ``nghttp2_error_code``, as parameter. But they are not detailed enough to debug. Therefore, we decided to use more detailed ``nghttp2_error`` values instead. The application using this callback should update the callback signature. If it treats ``error_code`` as HTTP/2 error code, update the code so that it is treated as ``nghttp2_error``. Receive client magic by default +++++++++++++++++++++++++++++++ Previously nghttp2 did not process client magic (24 bytes byte string). To make it deal with it, we had to use ``nghttp2_option_set_recv_client_preface()``. Since v1.0.0, nghttp2 processes client magic by default and ``nghttp2_option_set_recv_client_preface()`` was removed. Some application may want to disable this behaviour, so we added ``nghttp2_option_set_no_recv_client_magic()`` to achieve this. The application using ``nghttp2_option_set_recv_client_preface()`` with nonzero value, just remove it. The application using ``nghttp2_option_set_recv_client_preface()`` with zero value or not using it must use ``nghttp2_option_set_no_recv_client_magic()`` with nonzero value. Client, Server and Proxy programs --------------------------------- The ``src`` directory contains the HTTP/2 client, server and proxy programs. nghttp - client +++++++++++++++ ``nghttp`` is a HTTP/2 client. It can connect to the HTTP/2 server with prior knowledge, HTTP Upgrade and ALPN TLS extension. It has verbose output mode for framing information. Here is sample output from ``nghttp`` client: .. code-block:: text $ nghttp -nv https://nghttp2.org [ 0.190] Connected The negotiated protocol: h2 [ 0.212] recv SETTINGS frame (niv=2) [SETTINGS_MAX_CONCURRENT_STREAMS(0x03):100] [SETTINGS_INITIAL_WINDOW_SIZE(0x04):65535] [ 0.212] send SETTINGS frame (niv=2) [SETTINGS_MAX_CONCURRENT_STREAMS(0x03):100] [SETTINGS_INITIAL_WINDOW_SIZE(0x04):65535] [ 0.212] send SETTINGS frame ; ACK (niv=0) [ 0.212] send PRIORITY frame (dep_stream_id=0, weight=201, exclusive=0) [ 0.212] send PRIORITY frame (dep_stream_id=0, weight=101, exclusive=0) [ 0.212] send PRIORITY frame (dep_stream_id=0, weight=1, exclusive=0) [ 0.212] send PRIORITY frame (dep_stream_id=7, weight=1, exclusive=0) [ 0.212] send PRIORITY frame (dep_stream_id=3, weight=1, exclusive=0) [ 0.212] send HEADERS frame ; END_STREAM | END_HEADERS | PRIORITY (padlen=0, dep_stream_id=11, weight=16, exclusive=0) ; Open new stream :method: GET :path: / :scheme: https :authority: nghttp2.org accept: */* accept-encoding: gzip, deflate user-agent: nghttp2/1.0.1-DEV [ 0.221] recv SETTINGS frame ; ACK (niv=0) [ 0.221] recv (stream_id=13) :method: GET [ 0.221] recv (stream_id=13) :scheme: https [ 0.221] recv (stream_id=13) :path: /stylesheets/screen.css [ 0.221] recv (stream_id=13) :authority: nghttp2.org [ 0.221] recv (stream_id=13) accept-encoding: gzip, deflate [ 0.222] recv (stream_id=13) user-agent: nghttp2/1.0.1-DEV [ 0.222] recv PUSH_PROMISE frame ; END_HEADERS (padlen=0, promised_stream_id=2) [ 0.222] recv (stream_id=13) :status: 200 [ 0.222] recv (stream_id=13) date: Thu, 21 May 2015 16:38:14 GMT [ 0.222] recv (stream_id=13) content-type: text/html [ 0.222] recv (stream_id=13) last-modified: Fri, 15 May 2015 15:38:06 GMT [ 0.222] recv (stream_id=13) etag: W/"555612de-19f6" [ 0.222] recv (stream_id=13) link: ; rel=preload; as=stylesheet [ 0.222] recv (stream_id=13) content-encoding: gzip [ 0.222] recv (stream_id=13) server: nghttpx nghttp2/1.0.1-DEV [ 0.222] recv (stream_id=13) via: 1.1 nghttpx [ 0.222] recv (stream_id=13) strict-transport-security: max-age=31536000 [ 0.222] recv HEADERS frame ; END_HEADERS (padlen=0) ; First response header [ 0.222] recv DATA frame ; END_STREAM [ 0.222] recv (stream_id=2) :status: 200 [ 0.222] recv (stream_id=2) date: Thu, 21 May 2015 16:38:14 GMT [ 0.222] recv (stream_id=2) content-type: text/css [ 0.222] recv (stream_id=2) last-modified: Fri, 15 May 2015 15:38:06 GMT [ 0.222] recv (stream_id=2) etag: W/"555612de-9845" [ 0.222] recv (stream_id=2) content-encoding: gzip [ 0.222] recv (stream_id=2) server: nghttpx nghttp2/1.0.1-DEV [ 0.222] recv (stream_id=2) via: 1.1 nghttpx [ 0.222] recv (stream_id=2) strict-transport-security: max-age=31536000 [ 0.222] recv HEADERS frame ; END_HEADERS (padlen=0) ; First push response header [ 0.228] recv DATA frame ; END_STREAM [ 0.228] send GOAWAY frame (last_stream_id=2, error_code=NO_ERROR(0x00), opaque_data(0)=[]) The HTTP Upgrade is performed like so: .. code-block:: text $ nghttp -nvu http://nghttp2.org [ 0.011] Connected [ 0.011] HTTP Upgrade request GET / HTTP/1.1 Host: nghttp2.org Connection: Upgrade, HTTP2-Settings Upgrade: h2c HTTP2-Settings: AAMAAABkAAQAAP__ Accept: */* User-Agent: nghttp2/1.0.1-DEV [ 0.018] HTTP Upgrade response HTTP/1.1 101 Switching Protocols Connection: Upgrade Upgrade: h2c [ 0.018] HTTP Upgrade success [ 0.018] recv SETTINGS frame (niv=2) [SETTINGS_MAX_CONCURRENT_STREAMS(0x03):100] [SETTINGS_INITIAL_WINDOW_SIZE(0x04):65535] [ 0.018] send SETTINGS frame (niv=2) [SETTINGS_MAX_CONCURRENT_STREAMS(0x03):100] [SETTINGS_INITIAL_WINDOW_SIZE(0x04):65535] [ 0.018] send SETTINGS frame ; ACK (niv=0) [ 0.018] send PRIORITY frame (dep_stream_id=0, weight=201, exclusive=0) [ 0.018] send PRIORITY frame (dep_stream_id=0, weight=101, exclusive=0) [ 0.018] send PRIORITY frame (dep_stream_id=0, weight=1, exclusive=0) [ 0.018] send PRIORITY frame (dep_stream_id=7, weight=1, exclusive=0) [ 0.018] send PRIORITY frame (dep_stream_id=3, weight=1, exclusive=0) [ 0.018] send PRIORITY frame (dep_stream_id=11, weight=16, exclusive=0) [ 0.019] recv (stream_id=1) :method: GET [ 0.019] recv (stream_id=1) :scheme: http [ 0.019] recv (stream_id=1) :path: /stylesheets/screen.css [ 0.019] recv (stream_id=1) host: nghttp2.org [ 0.019] recv (stream_id=1) user-agent: nghttp2/1.0.1-DEV [ 0.019] recv PUSH_PROMISE frame ; END_HEADERS (padlen=0, promised_stream_id=2) [ 0.019] recv (stream_id=1) :status: 200 [ 0.019] recv (stream_id=1) date: Thu, 21 May 2015 16:39:16 GMT [ 0.019] recv (stream_id=1) content-type: text/html [ 0.019] recv (stream_id=1) content-length: 6646 [ 0.019] recv (stream_id=1) last-modified: Fri, 15 May 2015 15:38:06 GMT [ 0.019] recv (stream_id=1) etag: "555612de-19f6" [ 0.019] recv (stream_id=1) link: ; rel=preload; as=stylesheet [ 0.019] recv (stream_id=1) accept-ranges: bytes [ 0.019] recv (stream_id=1) server: nghttpx nghttp2/1.0.1-DEV [ 0.019] recv (stream_id=1) via: 1.1 nghttpx [ 0.019] recv HEADERS frame ; END_HEADERS (padlen=0) ; First response header [ 0.019] recv DATA frame ; END_STREAM [ 0.019] recv (stream_id=2) :status: 200 [ 0.019] recv (stream_id=2) date: Thu, 21 May 2015 16:39:16 GMT [ 0.019] recv (stream_id=2) content-type: text/css [ 0.019] recv (stream_id=2) content-length: 38981 [ 0.019] recv (stream_id=2) last-modified: Fri, 15 May 2015 15:38:06 GMT [ 0.019] recv (stream_id=2) etag: "555612de-9845" [ 0.019] recv (stream_id=2) accept-ranges: bytes [ 0.019] recv (stream_id=2) server: nghttpx nghttp2/1.0.1-DEV [ 0.019] recv (stream_id=2) via: 1.1 nghttpx [ 0.019] recv HEADERS frame ; END_HEADERS (padlen=0) ; First push response header [ 0.026] recv DATA frame [ 0.027] recv DATA frame [ 0.027] send WINDOW_UPDATE frame (window_size_increment=33343) [ 0.032] send WINDOW_UPDATE frame (window_size_increment=33707) [ 0.032] recv DATA frame ; END_STREAM [ 0.032] recv SETTINGS frame ; ACK (niv=0) [ 0.032] send GOAWAY frame (last_stream_id=2, error_code=NO_ERROR(0x00), opaque_data(0)=[]) Using the ``-s`` option, ``nghttp`` prints out some timing information for requests, sorted by completion time: .. code-block:: text $ nghttp -nas https://nghttp2.org/ ***** Statistics ***** Request timing: responseEnd: the time when last byte of response was received relative to connectEnd requestStart: the time just before first byte of request was sent relative to connectEnd. If '*' is shown, this was pushed by server. process: responseEnd - requestStart code: HTTP status code size: number of bytes received as response body without inflation. URI: request URI see http://www.w3.org/TR/resource-timing/#processing-model sorted by 'complete' id responseEnd requestStart process code size request path 13 +37.19ms +280us 36.91ms 200 2K / 2 +72.65ms * +36.38ms 36.26ms 200 8K /stylesheets/screen.css 17 +77.43ms +38.67ms 38.75ms 200 3K /javascripts/octopress.js 15 +78.12ms +38.66ms 39.46ms 200 3K /javascripts/modernizr-2.0.js Using the ``-r`` option, ``nghttp`` writes more detailed timing data to the given file in HAR format. nghttpd - server ++++++++++++++++ ``nghttpd`` is a multi-threaded static web server. By default, it uses SSL/TLS connection. Use ``--no-tls`` option to disable it. ``nghttpd`` only accepts HTTP/2 connections via ALPN or direct HTTP/2 connections. No HTTP Upgrade is supported. The ``-p`` option allows users to configure server push. Just like ``nghttp``, it has a verbose output mode for framing information. Here is sample output from ``nghttpd``: .. code-block:: text $ nghttpd --no-tls -v 8080 IPv4: listen 0.0.0.0:8080 IPv6: listen :::8080 [id=1] [ 1.521] send SETTINGS frame (niv=1) [SETTINGS_MAX_CONCURRENT_STREAMS(0x03):100] [id=1] [ 1.521] recv SETTINGS frame (niv=2) [SETTINGS_MAX_CONCURRENT_STREAMS(0x03):100] [SETTINGS_INITIAL_WINDOW_SIZE(0x04):65535] [id=1] [ 1.521] recv SETTINGS frame ; ACK (niv=0) [id=1] [ 1.521] recv PRIORITY frame (dep_stream_id=0, weight=201, exclusive=0) [id=1] [ 1.521] recv PRIORITY frame (dep_stream_id=0, weight=101, exclusive=0) [id=1] [ 1.521] recv PRIORITY frame (dep_stream_id=0, weight=1, exclusive=0) [id=1] [ 1.521] recv PRIORITY frame (dep_stream_id=7, weight=1, exclusive=0) [id=1] [ 1.521] recv PRIORITY frame (dep_stream_id=3, weight=1, exclusive=0) [id=1] [ 1.521] recv (stream_id=13) :method: GET [id=1] [ 1.521] recv (stream_id=13) :path: / [id=1] [ 1.521] recv (stream_id=13) :scheme: http [id=1] [ 1.521] recv (stream_id=13) :authority: localhost:8080 [id=1] [ 1.521] recv (stream_id=13) accept: */* [id=1] [ 1.521] recv (stream_id=13) accept-encoding: gzip, deflate [id=1] [ 1.521] recv (stream_id=13) user-agent: nghttp2/1.0.0-DEV [id=1] [ 1.521] recv HEADERS frame ; END_STREAM | END_HEADERS | PRIORITY (padlen=0, dep_stream_id=11, weight=16, exclusive=0) ; Open new stream [id=1] [ 1.521] send SETTINGS frame ; ACK (niv=0) [id=1] [ 1.521] send HEADERS frame ; END_HEADERS (padlen=0) ; First response header :status: 200 server: nghttpd nghttp2/1.0.0-DEV content-length: 10 cache-control: max-age=3600 date: Fri, 15 May 2015 14:49:04 GMT last-modified: Tue, 30 Sep 2014 12:40:52 GMT [id=1] [ 1.522] send DATA frame ; END_STREAM [id=1] [ 1.522] stream_id=13 closed [id=1] [ 1.522] recv GOAWAY frame (last_stream_id=0, error_code=NO_ERROR(0x00), opaque_data(0)=[]) [id=1] [ 1.522] closed nghttpx - proxy +++++++++++++++ ``nghttpx`` is a multi-threaded reverse proxy for HTTP/3, HTTP/2, and HTTP/1.1, and powers http://nghttp2.org and supports HTTP/2 server push. We reworked ``nghttpx`` command-line interface, and as a result, there are several incompatibles from 1.8.0 or earlier. This is necessary to extend its capability, and secure the further feature enhancements in the future release. Please read `Migration from nghttpx v1.8.0 or earlier `_ to know how to migrate from earlier releases. ``nghttpx`` implements `important performance-oriented features `_ in TLS, such as session IDs, session tickets (with automatic key rotation), OCSP stapling, dynamic record sizing, ALPN, forward secrecy and HTTP/2. ``nghttpx`` also offers the functionality to share session cache and ticket keys among multiple ``nghttpx`` instances via memcached. ``nghttpx`` has 2 operation modes: ================== ======================== ================ ============= Mode option Frontend Backend Note ================== ======================== ================ ============= default mode HTTP/3, HTTP/2, HTTP/1.1 HTTP/1.1, HTTP/2 Reverse proxy ``--http2-proxy`` HTTP/3, HTTP/2, HTTP/1.1 HTTP/1.1, HTTP/2 Forward proxy ================== ======================== ================ ============= The interesting mode at the moment is the default mode. It works like a reverse proxy and listens for HTTP/3, HTTP/2, and HTTP/1.1 and can be deployed as a SSL/TLS terminator for existing web server. In all modes, the frontend connections are encrypted by SSL/TLS by default. To disable encryption, use the ``no-tls`` keyword in ``--frontend`` option. If encryption is disabled, incoming HTTP/1.1 connections can be upgraded to HTTP/2 through HTTP Upgrade. On the other hard, backend connections are not encrypted by default. To encrypt backend connections, use ``tls`` keyword in ``--backend`` option. ``nghttpx`` supports a configuration file. See the ``--conf`` option and sample configuration file ``nghttpx.conf.sample``. In the default mode, ``nghttpx`` works as reverse proxy to the backend server: .. code-block:: text Client <-- (HTTP/3, HTTP/2, HTTP/1.1) --> nghttpx <-- (HTTP/1.1, HTTP/2) --> Web Server [reverse proxy] With the ``--http2-proxy`` option, it works as forward proxy, and it is so called secure HTTP/2 proxy: .. code-block:: text Client <-- (HTTP/3, HTTP/2, HTTP/1.1) --> nghttpx <-- (HTTP/1.1) --> Proxy [secure proxy] (e.g., Squid, ATS) The ``Client`` in the above example needs to be configured to use ``nghttpx`` as secure proxy. At the time of this writing, both Chrome and Firefox support secure HTTP/2 proxy. One way to configure Chrome to use a secure proxy is to create a proxy.pac script like this: .. code-block:: javascript function FindProxyForURL(url, host) { return "HTTPS SERVERADDR:PORT"; } ``SERVERADDR`` and ``PORT`` is the hostname/address and port of the machine nghttpx is running on. Please note that Chrome requires a valid certificate for secure proxy. Then run Chrome with the following arguments: .. code-block:: text $ google-chrome --proxy-pac-url=file:///path/to/proxy.pac --use-npn The backend HTTP/2 connections can be tunneled through an HTTP proxy. The proxy is specified using ``--backend-http-proxy-uri``. The following figure illustrates how nghttpx talks to the outside HTTP/2 proxy through an HTTP proxy: .. code-block:: text Client <-- (HTTP/3, HTTP/2, HTTP/1.1) --> nghttpx <-- (HTTP/2) -- --===================---> HTTP/2 Proxy (HTTP proxy tunnel) (e.g., nghttpx -s) Benchmarking tool ----------------- The ``h2load`` program is a benchmarking tool for HTTP/3, HTTP/2, and HTTP/1.1. The UI of ``h2load`` is heavily inspired by ``weighttp`` (https://github.com/lighttpd/weighttp). The typical usage is as follows: .. code-block:: text $ h2load -n100000 -c100 -m100 https://localhost:8443/ starting benchmark... spawning thread #0: 100 concurrent clients, 100000 total requests Protocol: TLSv1.2 Cipher: ECDHE-RSA-AES128-GCM-SHA256 Server Temp Key: ECDH P-256 256 bits progress: 10% done progress: 20% done progress: 30% done progress: 40% done progress: 50% done progress: 60% done progress: 70% done progress: 80% done progress: 90% done progress: 100% done finished in 771.26ms, 129658 req/s, 4.71MB/s requests: 100000 total, 100000 started, 100000 done, 100000 succeeded, 0 failed, 0 errored status codes: 100000 2xx, 0 3xx, 0 4xx, 0 5xx traffic: 3812300 bytes total, 1009900 bytes headers, 1000000 bytes data min max mean sd +/- sd time for request: 25.12ms 124.55ms 51.07ms 15.36ms 84.87% time for connect: 208.94ms 254.67ms 241.38ms 7.95ms 63.00% time to 1st byte: 209.11ms 254.80ms 241.51ms 7.94ms 63.00% The above example issued total 100,000 requests, using 100 concurrent clients (in other words, 100 HTTP/2 sessions), and a maximum of 100 streams per client. With the ``-t`` option, ``h2load`` will use multiple native threads to avoid saturating a single core on client side. .. warning:: **Don't use this tool against publicly available servers.** That is considered a DOS attack. Please only use it against your private servers. If the experimental HTTP/3 is enabled, h2load can send requests to HTTP/3 server. To do this, specify ``h3`` to ``--alpn-list`` option like so: .. code-block:: text $ h2load --alpn-list h3 https://127.0.0.1:4433 For nghttp2 v1.58 or earlier, use ``--npn-list`` instead of ``--alpn-list``. HPACK tools ----------- The ``src`` directory contains the HPACK tools. The ``deflatehd`` program is a command-line header compression tool. The ``inflatehd`` program is a command-line header decompression tool. Both tools read input from stdin and write output to stdout. Errors are written to stderr. They take JSON as input and output. We (mostly) use the same JSON data format described at https://github.com/http2jp/hpack-test-case. deflatehd - header compressor +++++++++++++++++++++++++++++ The ``deflatehd`` program reads JSON data or HTTP/1-style header fields from stdin and outputs compressed header block in JSON. For the JSON input, the root JSON object must include a ``cases`` key. Its value has to include the sequence of input header set. They share the same compression context and are processed in the order they appear. Each item in the sequence is a JSON object and it must include a ``headers`` key. Its value is an array of JSON objects, which includes exactly one name/value pair. Example: .. code-block:: json { "cases": [ { "headers": [ { ":method": "GET" }, { ":path": "/" } ] }, { "headers": [ { ":method": "POST" }, { ":path": "/" } ] } ] } With the ``-t`` option, the program can accept more familiar HTTP/1 style header field blocks. Each header set is delimited by an empty line: Example: .. code-block:: text :method: GET :scheme: https :path: / :method: POST user-agent: nghttp2 The output is in JSON object. It should include a ``cases`` key and its value is an array of JSON objects, which has at least the following keys: seq The index of header set in the input. input_length The sum of the length of the name/value pairs in the input. output_length The length of the compressed header block. percentage_of_original_size ``output_length`` / ``input_length`` * 100 wire The compressed header block as a hex string. headers The input header set. header_table_size The header table size adjusted before deflating the header set. Examples: .. code-block:: json { "cases": [ { "seq": 0, "input_length": 66, "output_length": 20, "percentage_of_original_size": 30.303030303030305, "wire": "01881f3468e5891afcbf83868a3d856659c62e3f", "headers": [ { ":authority": "example.org" }, { ":method": "GET" }, { ":path": "/" }, { ":scheme": "https" }, { "user-agent": "nghttp2" } ], "header_table_size": 4096 } , { "seq": 1, "input_length": 74, "output_length": 10, "percentage_of_original_size": 13.513513513513514, "wire": "88448504252dd5918485", "headers": [ { ":authority": "example.org" }, { ":method": "POST" }, { ":path": "/account" }, { ":scheme": "https" }, { "user-agent": "nghttp2" } ], "header_table_size": 4096 } ] } The output can be used as the input for ``inflatehd`` and ``deflatehd``. With the ``-d`` option, the extra ``header_table`` key is added and its associated value includes the state of dynamic header table after the corresponding header set was processed. The value includes at least the following keys: entries The entry in the header table. If ``referenced`` is ``true``, it is in the reference set. The ``size`` includes the overhead (32 bytes). The ``index`` corresponds to the index of header table. The ``name`` is the header field name and the ``value`` is the header field value. size The sum of the spaces entries occupied, this includes the entry overhead. max_size The maximum header table size. deflate_size The sum of the spaces entries occupied within ``max_deflate_size``. max_deflate_size The maximum header table size the encoder uses. This can be smaller than ``max_size``. In this case, the encoder only uses up to first ``max_deflate_size`` buffer. Since the header table size is still ``max_size``, the encoder has to keep track of entries outside the ``max_deflate_size`` but inside the ``max_size`` and make sure that they are no longer referenced. Example: .. code-block:: json { "cases": [ { "seq": 0, "input_length": 66, "output_length": 20, "percentage_of_original_size": 30.303030303030305, "wire": "01881f3468e5891afcbf83868a3d856659c62e3f", "headers": [ { ":authority": "example.org" }, { ":method": "GET" }, { ":path": "/" }, { ":scheme": "https" }, { "user-agent": "nghttp2" } ], "header_table_size": 4096, "header_table": { "entries": [ { "index": 1, "name": "user-agent", "value": "nghttp2", "referenced": true, "size": 49 }, { "index": 2, "name": ":scheme", "value": "https", "referenced": true, "size": 44 }, { "index": 3, "name": ":path", "value": "/", "referenced": true, "size": 38 }, { "index": 4, "name": ":method", "value": "GET", "referenced": true, "size": 42 }, { "index": 5, "name": ":authority", "value": "example.org", "referenced": true, "size": 53 } ], "size": 226, "max_size": 4096, "deflate_size": 226, "max_deflate_size": 4096 } } , { "seq": 1, "input_length": 74, "output_length": 10, "percentage_of_original_size": 13.513513513513514, "wire": "88448504252dd5918485", "headers": [ { ":authority": "example.org" }, { ":method": "POST" }, { ":path": "/account" }, { ":scheme": "https" }, { "user-agent": "nghttp2" } ], "header_table_size": 4096, "header_table": { "entries": [ { "index": 1, "name": ":method", "value": "POST", "referenced": true, "size": 43 }, { "index": 2, "name": "user-agent", "value": "nghttp2", "referenced": true, "size": 49 }, { "index": 3, "name": ":scheme", "value": "https", "referenced": true, "size": 44 }, { "index": 4, "name": ":path", "value": "/", "referenced": false, "size": 38 }, { "index": 5, "name": ":method", "value": "GET", "referenced": false, "size": 42 }, { "index": 6, "name": ":authority", "value": "example.org", "referenced": true, "size": 53 } ], "size": 269, "max_size": 4096, "deflate_size": 269, "max_deflate_size": 4096 } } ] } inflatehd - header decompressor +++++++++++++++++++++++++++++++ The ``inflatehd`` program reads JSON data from stdin and outputs decompressed name/value pairs in JSON. The root JSON object must include the ``cases`` key. Its value has to include the sequence of compressed header blocks. They share the same compression context and are processed in the order they appear. Each item in the sequence is a JSON object and it must have at least a ``wire`` key. Its value is a compressed header block as a hex string. Example: .. code-block:: json { "cases": [ { "wire": "8285" }, { "wire": "8583" } ] } The output is a JSON object. It should include a ``cases`` key and its value is an array of JSON objects, which has at least following keys: seq The index of the header set in the input. headers A JSON array that includes decompressed name/value pairs. wire The compressed header block as a hex string. header_table_size The header table size adjusted before inflating compressed header block. Example: .. code-block:: json { "cases": [ { "seq": 0, "wire": "01881f3468e5891afcbf83868a3d856659c62e3f", "headers": [ { ":authority": "example.org" }, { ":method": "GET" }, { ":path": "/" }, { ":scheme": "https" }, { "user-agent": "nghttp2" } ], "header_table_size": 4096 } , { "seq": 1, "wire": "88448504252dd5918485", "headers": [ { ":method": "POST" }, { ":path": "/account" }, { "user-agent": "nghttp2" }, { ":scheme": "https" }, { ":authority": "example.org" } ], "header_table_size": 4096 } ] } The output can be used as the input for ``deflatehd`` and ``inflatehd``. With the ``-d`` option, the extra ``header_table`` key is added and its associated value includes the state of the dynamic header table after the corresponding header set was processed. The format is the same as ``deflatehd``. Contribution ------------ [This text was composed based on 1.2. License section of curl/libcurl project.] When contributing with code, you agree to put your changes and new code under the same license nghttp2 is already using unless stated and agreed otherwise. When changing existing source code, do not alter the copyright of the original file(s). The copyright will still be owned by the original creator(s) or those who have been assigned copyright by the original author(s). By submitting a patch to the nghttp2 project, you (or your employer, as the case may be) agree to assign the copyright of your submission to us. .. the above really needs to be reworded to pass legal muster. We will credit you for your changes as far as possible, to give credit but also to keep a trace back to who made what changes. Please always provide us with your full real name when contributing! See `Contribution Guidelines `_ for more details. Versioning ---------- In general, we follow `Semantic Versioning `_. We may release PATCH releases between the regular releases, mainly for severe security bug fixes. We have no plan to break API compatibility changes involving soname bump, so MAJOR version will stay 1 for the foreseeable future. License ------- The MIT License nghttp2/fetch-ocsp-response000075500000021432147633146710011765 0ustar00#!/usr/bin/env python # -*- coding: utf-8 -*- # nghttp2 - HTTP/2 C Library # Copyright (c) 2015 Tatsuhiro Tsujikawa # Permission is hereby granted, free of charge, to any person obtaining # a copy of this software and associated documentation files (the # "Software"), to deal in the Software without restriction, including # without limitation the rights to use, copy, modify, merge, publish, # distribute, sublicense, and/or sell copies of the Software, and to # permit persons to whom the Software is furnished to do so, subject to # the following conditions: # The above copyright notice and this permission notice shall be # included in all copies or substantial portions of the Software. # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, # EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF # MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND # NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE # LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # This program was translated from the program originally developed by # h2o project (https://github.com/h2o/h2o), written in Perl. It had # the following copyright notice: # Copyright (c) 2015 DeNA Co., Ltd. # # Permission is hereby granted, free of charge, to any person obtaining a copy # of this software and associated documentation files (the "Software"), to # deal in the Software without restriction, including without limitation the # rights to use, copy, modify, merge, publish, distribute, sublicense, and/or # sell copies of the Software, and to permit persons to whom the Software is # furnished to do so, subject to the following conditions: # # The above copyright notice and this permission notice shall be included in # all copies or substantial portions of the Software. # # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS # IN THE SOFTWARE. from __future__ import unicode_literals import argparse import io import os import os.path import re import shutil import subprocess import sys import tempfile # make this program work for both Python 3 and Python 2. try: from urllib.parse import urlparse stdout_bwrite = sys.stdout.buffer.write except ImportError: from urlparse import urlparse stdout_bwrite = sys.stdout.write def die(msg): sys.stderr.write(msg) sys.stderr.write('\n') sys.exit(255) def tempfail(msg): sys.stderr.write(msg) sys.stderr.write('\n') sys.exit(os.EX_TEMPFAIL) def run_openssl(args, allow_tempfail=False): buf = io.BytesIO() try: p = subprocess.Popen(args, stdout=subprocess.PIPE) except Exception as e: die('failed to invoke {}:{}'.format(args, e)) try: while True: data = p.stdout.read() if len(data) == 0: break buf.write(data) if p.wait() != 0: raise Exception('nonzero return code {}'.format(p.returncode)) return buf.getvalue() except Exception as e: msg = 'OpenSSL exited abnormally: {}:{}'.format(args, e) tempfail(msg) if allow_tempfail else die(msg) def read_file(path): with open(path, 'rb') as f: return f.read() def write_file(path, data): with open(path, 'wb') as f: f.write(data) def detect_openssl_version(cmd): return run_openssl([cmd, 'version']).decode('utf-8').strip() def extract_ocsp_uri(cmd, cert_fn): # obtain ocsp uri ocsp_uri = run_openssl( [cmd, 'x509', '-in', cert_fn, '-noout', '-ocsp_uri']).decode('utf-8').strip() if not re.match(r'^https?://', ocsp_uri): die('failed to extract ocsp URI from {}'.format(cert_fn)) return ocsp_uri def save_issuer_certificate(issuer_fn, cert_fn): # save issuer certificate chain = read_file(cert_fn).decode('utf-8') m = re.match( r'.*?-----END CERTIFICATE-----.*?(-----BEGIN CERTIFICATE-----.*?-----END CERTIFICATE-----)', chain, re.DOTALL) if not m: die('--issuer option was not used, and failed to extract issuer certificate from the certificate') write_file(issuer_fn, (m.group(1) + '\n').encode('utf-8')) def send_and_receive_ocsp(respder_fn, cmd, cert_fn, issuer_fn, ocsp_uri, ocsp_host, openssl_version): # obtain response (without verification) sys.stderr.write('sending OCSP request to {}\n'.format(ocsp_uri)) args = [ cmd, 'ocsp', '-issuer', issuer_fn, '-cert', cert_fn, '-url', ocsp_uri, '-noverify', '-respout', respder_fn ] ver = openssl_version.lower() if ver.startswith('openssl 1.0.') or ver.startswith('libressl '): args.extend(['-header', 'Host', ocsp_host]) resp = run_openssl(args, allow_tempfail=True) return resp.decode('utf-8') def verify_response(cmd, tempdir, issuer_fn, respder_fn): # verify the response sys.stderr.write('verifying the response signature\n') verify_fn = os.path.join(tempdir, 'verify.out') # try from exotic options allextra = [ # for comodo ['-VAfile', issuer_fn], # these options are only available in OpenSSL >= 1.0.2 ['-partial_chain', '-trusted_first', '-CAfile', issuer_fn], # for OpenSSL <= 1.0.1 ['-CAfile', issuer_fn], ] for extra in allextra: with open(verify_fn, 'w+b') as f: args = [cmd, 'ocsp', '-respin', respder_fn] args.extend(extra) p = subprocess.Popen(args, stdout=f, stderr=f) if p.wait() == 0: # OpenSSL <= 1.0.1, openssl ocsp still returns exit # code 0 even if verification was failed. So check # the error message in stderr output. f.seek(0) if f.read().decode('utf-8').find( 'Response Verify Failure') != -1: continue sys.stderr.write('verify OK (used: {})\n'.format(extra)) return True sys.stderr.write(read_file(verify_fn).decode('utf-8')) return False def fetch_ocsp_response(cmd, cert_fn, tempdir, issuer_fn=None): openssl_version = detect_openssl_version(cmd) sys.stderr.write( 'fetch-ocsp-response (using {})\n'.format(openssl_version)) ocsp_uri = extract_ocsp_uri(cmd, cert_fn) ocsp_host = urlparse(ocsp_uri).netloc if not issuer_fn: issuer_fn = os.path.join(tempdir, 'issuer.crt') save_issuer_certificate(issuer_fn, cert_fn) respder_fn = os.path.join(tempdir, 'resp.der') resp = send_and_receive_ocsp( respder_fn, cmd, cert_fn, issuer_fn, ocsp_uri, ocsp_host, openssl_version) sys.stderr.write('{}\n'.format(resp)) # OpenSSL 1.0.2 still returns exit code 0 even if ocsp responder # returned error status (e.g., trylater(3)) if resp.find('Responder Error:') != -1: raise Exception('responder returned error') if not verify_response(cmd, tempdir, issuer_fn, respder_fn): tempfail('failed to verify the response') # success res = read_file(respder_fn) stdout_bwrite(res) if __name__ == '__main__': parser = argparse.ArgumentParser( description= '''The command issues an OCSP request for given server certificate, verifies the response and prints the resulting DER.''', epilog= '''The command exits 0 if successful, or 75 (EX_TEMPFAIL) on temporary error. Other exit codes may be returned in case of hard errors.''') parser.add_argument( '--issuer', metavar='FILE', help= 'issuer certificate (if omitted, is extracted from the certificate chain)') parser.add_argument('--openssl', metavar='CMD', help='openssl command to use (default: "openssl")', default='openssl') parser.add_argument('certificate', help='path to certificate file to validate') args = parser.parse_args() tempdir = None try: # Python3.2 has tempfile.TemporaryDirectory, which has nice # feature to delete its tree by cleanup() function. We have # to support Python2.7, so we have to do this manually. tempdir = tempfile.mkdtemp() fetch_ocsp_response(args.openssl, args.certificate, tempdir, args.issuer) finally: if tempdir: shutil.rmtree(tempdir)