diff options
Diffstat (limited to '')
36 files changed, 7049 insertions, 0 deletions
diff --git a/web/server/h2o/libh2o/src/main.c b/web/server/h2o/libh2o/src/main.c new file mode 100644 index 00000000..af0867f2 --- /dev/null +++ b/web/server/h2o/libh2o/src/main.c @@ -0,0 +1,2239 @@ +/* + * Copyright (c) 2014-2016 DeNA Co., Ltd., Kazuho Oku, Tatsuhiko Kubo, + * Domingo Alvarez Duarte, Nick Desaulniers, + * Jeff Marrison, Shota Fukumori, Fastly, Inc. + * + * 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. + */ +#include <arpa/inet.h> +#include <assert.h> +#include <errno.h> +#include <fcntl.h> +#include <getopt.h> +#include <inttypes.h> +#include <limits.h> +#include <netdb.h> +#include <netinet/in.h> +#include <netinet/tcp.h> +#include <poll.h> +#include <pthread.h> +#include <pwd.h> +#include <signal.h> +#include <spawn.h> +#include <stdio.h> +#include <unistd.h> +#include <sys/resource.h> +#include <sys/stat.h> +#include <sys/socket.h> +#include <sys/time.h> +#include <sys/types.h> +#include <sys/un.h> +#include <sys/wait.h> +#include <openssl/crypto.h> +#include <openssl/err.h> +#include <openssl/ssl.h> +#ifdef __GLIBC__ +#include <execinfo.h> +#endif +#if H2O_USE_PICOTLS +#include "picotls.h" +#include "picotls/minicrypto.h" +#include "picotls/openssl.h" +#endif +#include "cloexec.h" +#include "yoml-parser.h" +#include "neverbleed.h" +#include "h2o.h" +#include "h2o/configurator.h" +#include "h2o/http1.h" +#include "h2o/http2.h" +#include "h2o/serverutil.h" +#if H2O_USE_MRUBY +#include "h2o/mruby_.h" +#endif +#include "standalone.h" + +#ifdef TCP_FASTOPEN +#define H2O_DEFAULT_LENGTH_TCP_FASTOPEN_QUEUE 4096 +#else +#define H2O_DEFAULT_LENGTH_TCP_FASTOPEN_QUEUE 0 +#endif + +#define H2O_DEFAULT_NUM_NAME_RESOLUTION_THREADS 32 + +#define H2O_DEFAULT_OCSP_UPDATER_MAX_THREADS 10 + +#if defined(OPENSSL_NO_OCSP) && !H2O_USE_PICOTLS +#define H2O_USE_OCSP 0 +#else +#define H2O_USE_OCSP 1 +#endif + +struct listener_ssl_config_t { + H2O_VECTOR(h2o_iovec_t) hostnames; + char *certificate_file; + SSL_CTX *ctx; +#if H2O_USE_OCSP + struct { + uint64_t interval; + unsigned max_failures; + char *cmd; + pthread_t updater_tid; /* should be valid when and only when interval != 0 */ + struct { + pthread_mutex_t mutex; + h2o_buffer_t *data; + } response; + } ocsp_stapling; +#endif +}; + +struct listener_config_t { + int fd; + struct sockaddr_storage addr; + socklen_t addrlen; + h2o_hostconf_t **hosts; + H2O_VECTOR(struct listener_ssl_config_t *) ssl; + int proxy_protocol; +}; + +struct listener_ctx_t { + h2o_accept_ctx_t accept_ctx; + h2o_socket_t *sock; +}; + +typedef struct st_resolve_tag_node_cache_entry_t { + h2o_iovec_t filename; + yoml_t *node; +} resolve_tag_node_cache_entry_t; + +typedef struct st_resolve_tag_arg_t { + H2O_VECTOR(resolve_tag_node_cache_entry_t) node_cache; +} resolve_tag_arg_t; + +typedef enum en_run_mode_t { + RUN_MODE_WORKER = 0, + RUN_MODE_MASTER, + RUN_MODE_DAEMON, + RUN_MODE_TEST, +} run_mode_t; + +static struct { + h2o_globalconf_t globalconf; + run_mode_t run_mode; + struct { + int *fds; + char *bound_fd_map; /* has `num_fds` elements, set to 1 if fd[index] was bound to one of the listeners */ + size_t num_fds; + char *env_var; + } server_starter; + struct listener_config_t **listeners; + size_t num_listeners; + char *pid_file; + char *error_log; + int max_connections; + size_t num_threads; + int tfo_queues; + time_t launch_time; + struct { + pthread_t tid; + h2o_context_t ctx; + h2o_multithread_receiver_t server_notifications; + h2o_multithread_receiver_t memcached; + } * threads; + volatile sig_atomic_t shutdown_requested; + h2o_barrier_t startup_sync_barrier; + struct { + /* unused buffers exist to avoid false sharing of the cache line */ + char _unused1_avoir_false_sharing[32]; + int _num_connections; /* number of currently handled incoming connections, should use atomic functions to update the value + */ + char _unused2_avoir_false_sharing[32]; + unsigned long + _num_sessions; /* total number of opened incoming connections, should use atomic functions to update the value */ + char _unused3_avoir_false_sharing[32]; + } state; + char *crash_handler; + int crash_handler_wait_pipe_close; +} conf = { + {NULL}, /* globalconf */ + RUN_MODE_WORKER, /* dry-run */ + {NULL}, /* server_starter */ + NULL, /* listeners */ + 0, /* num_listeners */ + NULL, /* pid_file */ + NULL, /* error_log */ + 1024, /* max_connections */ + 0, /* initialized in main() */ + 0, /* initialized in main() */ + 0, /* initialized in main() */ + NULL, /* thread_ids */ + 0, /* shutdown_requested */ + H2O_BARRIER_INITIALIZER(SIZE_MAX), /* startup_sync_barrier */ + {{0}}, /* state */ + "share/h2o/annotate-backtrace-symbols", /* crash_handler */ + 0, /* crash_handler_wait_pipe_close */ +}; + +static neverbleed_t *neverbleed = NULL; + +static void set_cloexec(int fd) +{ + if (fcntl(fd, F_SETFD, FD_CLOEXEC) == -1) { + perror("failed to set FD_CLOEXEC"); + abort(); + } +} + +static int on_openssl_print_errors(const char *str, size_t len, void *fp) +{ + fwrite(str, 1, len, fp); + return (int)len; +} + +static void setup_ecc_key(SSL_CTX *ssl_ctx) +{ +#ifdef SSL_CTX_set_ecdh_auto + SSL_CTX_set_ecdh_auto(ssl_ctx, 1); +#else + int nid = NID_X9_62_prime256v1; + EC_KEY *key = EC_KEY_new_by_curve_name(nid); + if (key == NULL) { + fprintf(stderr, "Failed to create curve \"%s\"\n", OBJ_nid2sn(nid)); + return; + } + SSL_CTX_set_tmp_ecdh(ssl_ctx, key); + EC_KEY_free(key); +#endif +} + +static struct listener_ssl_config_t *resolve_sni(struct listener_config_t *listener, const char *name, size_t name_len) +{ + size_t i, j; + + for (i = 0; i != listener->ssl.size; ++i) { + struct listener_ssl_config_t *ssl_config = listener->ssl.entries[i]; + for (j = 0; j != ssl_config->hostnames.size; ++j) { + if (ssl_config->hostnames.entries[j].base[0] == '*') { + /* matching against "*.foo.bar" */ + size_t cmplen = ssl_config->hostnames.entries[j].len - 1; + if (!(cmplen < name_len && h2o_lcstris(name + name_len - cmplen, cmplen, ssl_config->hostnames.entries[j].base + 1, + ssl_config->hostnames.entries[j].len - 1))) + continue; + } else { + if (!h2o_lcstris(name, name_len, ssl_config->hostnames.entries[j].base, ssl_config->hostnames.entries[j].len)) + continue; + } + /* found */ + return listener->ssl.entries[i]; + } + } + return listener->ssl.entries[0]; +} + +static int on_sni_callback(SSL *ssl, int *ad, void *arg) +{ + struct listener_config_t *listener = arg; + const char *server_name = SSL_get_servername(ssl, TLSEXT_NAMETYPE_host_name); + + if (server_name != NULL) { + struct listener_ssl_config_t *resolved = resolve_sni(listener, server_name, strlen(server_name)); + if (resolved->ctx != SSL_get_SSL_CTX(ssl)) + SSL_set_SSL_CTX(ssl, resolved->ctx); + } + + return SSL_TLSEXT_ERR_OK; +} + +#if H2O_USE_PICOTLS +struct st_on_client_hello_ptls_t { + ptls_on_client_hello_t super; + struct listener_config_t *listener; +}; + +static int on_client_hello_ptls(ptls_on_client_hello_t *_self, ptls_t *tls, ptls_iovec_t server_name, + const ptls_iovec_t *negotiated_protocols, size_t num_negotiated_protocols, + const uint16_t *signature_algorithms, size_t num_signature_algorithms) +{ + struct st_on_client_hello_ptls_t *self = (struct st_on_client_hello_ptls_t *)_self; + int ret = 0; + + /* handle SNI */ + if (server_name.base != NULL) { + struct listener_ssl_config_t *resolved = resolve_sni(self->listener, (const char *)server_name.base, server_name.len); + ptls_context_t *newctx = h2o_socket_ssl_get_picotls_context(resolved->ctx); + ptls_set_context(tls, newctx); + ptls_set_server_name(tls, (const char *)server_name.base, server_name.len); + } + + /* handle ALPN */ + if (num_negotiated_protocols != 0) { + const h2o_iovec_t *server_pref; + for (server_pref = h2o_alpn_protocols; server_pref->len != 0; ++server_pref) { + size_t i; + for (i = 0; i != num_negotiated_protocols; ++i) + if (h2o_memis(server_pref->base, server_pref->len, negotiated_protocols[i].base, negotiated_protocols[i].len)) + goto ALPN_Found; + } + return PTLS_ALERT_NO_APPLICATION_PROTOCOL; + ALPN_Found: + if ((ret = ptls_set_negotiated_protocol(tls, server_pref->base, server_pref->len)) != 0) + return ret; + } + + return ret; +} +#endif + +static void update_ocsp_stapling(struct listener_ssl_config_t *ssl_conf, h2o_buffer_t *resp) +{ + pthread_mutex_lock(&ssl_conf->ocsp_stapling.response.mutex); + if (ssl_conf->ocsp_stapling.response.data != NULL) + h2o_buffer_dispose(&ssl_conf->ocsp_stapling.response.data); + ssl_conf->ocsp_stapling.response.data = resp; + pthread_mutex_unlock(&ssl_conf->ocsp_stapling.response.mutex); +} + +static int get_ocsp_response(const char *cert_fn, const char *cmd, h2o_buffer_t **resp) +{ + char *cmd_fullpath = h2o_configurator_get_cmd_path(cmd), *argv[] = {cmd_fullpath, (char *)cert_fn, NULL}; + int child_status, ret; + + if (h2o_read_command(cmd_fullpath, argv, resp, &child_status) != 0) { + fprintf(stderr, "[OCSP Stapling] failed to execute %s:%s\n", cmd, strerror(errno)); + switch (errno) { + case EACCES: + case ENOENT: + case ENOEXEC: + /* permanent errors */ + ret = EX_CONFIG; + goto Exit; + default: + ret = EX_TEMPFAIL; + goto Exit; + } + } + + if (!(WIFEXITED(child_status) && WEXITSTATUS(child_status) == 0)) + h2o_buffer_dispose(resp); + if (!WIFEXITED(child_status)) { + fprintf(stderr, "[OCSP Stapling] command %s was killed by signal %d\n", cmd_fullpath, WTERMSIG(child_status)); + ret = EX_TEMPFAIL; + goto Exit; + } + ret = WEXITSTATUS(child_status); + +Exit: + free(cmd_fullpath); + return ret; +} + +static h2o_sem_t ocsp_updater_semaphore; + +static void *ocsp_updater_thread(void *_ssl_conf) +{ + struct listener_ssl_config_t *ssl_conf = _ssl_conf; + time_t next_at = 0, now; + unsigned fail_cnt = 0; + int status; + h2o_buffer_t *resp; + + assert(ssl_conf->ocsp_stapling.interval != 0); + + while (1) { + /* sleep until next_at */ + if ((now = time(NULL)) < next_at) { + time_t sleep_secs = next_at - now; + sleep(sleep_secs < UINT_MAX ? (unsigned)sleep_secs : UINT_MAX); + continue; + } + /* fetch the response */ + h2o_sem_wait(&ocsp_updater_semaphore); + status = get_ocsp_response(ssl_conf->certificate_file, ssl_conf->ocsp_stapling.cmd, &resp); + h2o_sem_post(&ocsp_updater_semaphore); + switch (status) { + case 0: /* success */ + fail_cnt = 0; + update_ocsp_stapling(ssl_conf, resp); + fprintf(stderr, "[OCSP Stapling] successfully updated the response for certificate file:%s\n", + ssl_conf->certificate_file); + break; + case EX_TEMPFAIL: /* temporary failure */ + if (fail_cnt == ssl_conf->ocsp_stapling.max_failures) { + fprintf(stderr, + "[OCSP Stapling] OCSP stapling is temporary disabled due to repeated errors for certificate file:%s\n", + ssl_conf->certificate_file); + update_ocsp_stapling(ssl_conf, NULL); + } else { + fprintf(stderr, "[OCSP Stapling] reusing old response due to a temporary error occurred while fetching OCSP " + "response for certificate file:%s\n", + ssl_conf->certificate_file); + ++fail_cnt; + } + break; + default: /* permanent failure */ + update_ocsp_stapling(ssl_conf, NULL); + fprintf(stderr, "[OCSP Stapling] disabled for certificate file:%s\n", ssl_conf->certificate_file); + goto Exit; + } + /* update next_at */ + next_at = time(NULL) + ssl_conf->ocsp_stapling.interval; + } + +Exit: + return NULL; +} + +#ifndef OPENSSL_NO_OCSP + +static int on_staple_ocsp_ossl(SSL *ssl, void *_ssl_conf) +{ + struct listener_ssl_config_t *ssl_conf = _ssl_conf; + void *resp = NULL; + size_t len = 0; + + /* fetch ocsp response */ + pthread_mutex_lock(&ssl_conf->ocsp_stapling.response.mutex); + if (ssl_conf->ocsp_stapling.response.data != NULL) { + resp = CRYPTO_malloc((int)ssl_conf->ocsp_stapling.response.data->size, __FILE__, __LINE__); + if (resp != NULL) { + len = ssl_conf->ocsp_stapling.response.data->size; + memcpy(resp, ssl_conf->ocsp_stapling.response.data->bytes, len); + } + } + pthread_mutex_unlock(&ssl_conf->ocsp_stapling.response.mutex); + + if (resp != NULL) { + SSL_set_tlsext_status_ocsp_resp(ssl, resp, len); + return SSL_TLSEXT_ERR_OK; + } else { + return SSL_TLSEXT_ERR_NOACK; + } +} + +#endif + +#if H2O_USE_PICOTLS + +struct st_staple_ocsp_ptls_t { + ptls_staple_ocsp_t super; + struct listener_ssl_config_t *conf; +}; + +static int on_staple_ocsp_ptls(ptls_staple_ocsp_t *_self, ptls_t *tls, ptls_buffer_t *output, size_t cert_index) +{ + struct st_staple_ocsp_ptls_t *self = (struct st_staple_ocsp_ptls_t *)_self; + int locked = 0, ret; + + if (cert_index != 0) { + ret = PTLS_ERROR_LIBRARY; + goto Exit; + } + + pthread_mutex_lock(&self->conf->ocsp_stapling.response.mutex); + locked = 1; + + if (self->conf->ocsp_stapling.response.data == NULL) { + ret = PTLS_ERROR_LIBRARY; + goto Exit; + } + ptls_buffer_pushv(output, self->conf->ocsp_stapling.response.data->bytes, self->conf->ocsp_stapling.response.data->size); + ret = 0; + +Exit: + if (locked) + pthread_mutex_unlock(&self->conf->ocsp_stapling.response.mutex); + return ret; +} + +static const char *listener_setup_ssl_picotls(struct listener_config_t *listener, struct listener_ssl_config_t *ssl_config, + SSL_CTX *ssl_ctx) +{ + static const ptls_key_exchange_algorithm_t *key_exchanges[] = {&ptls_minicrypto_x25519, &ptls_openssl_secp256r1, NULL}; + struct st_fat_context_t { + ptls_context_t ctx; + struct st_on_client_hello_ptls_t ch; + struct st_staple_ocsp_ptls_t so; + ptls_openssl_sign_certificate_t sc; + } *pctx = h2o_mem_alloc(sizeof(*pctx)); + EVP_PKEY *key; + X509 *cert; + STACK_OF(X509) * cert_chain; + int ret; + + *pctx = (struct st_fat_context_t){{ptls_openssl_random_bytes, + &ptls_get_time, + key_exchanges, + ptls_openssl_cipher_suites, + {NULL, 0}, + &pctx->ch.super, + &pctx->so.super, + &pctx->sc.super, + NULL, + 0, + 8192, + 1}, + {{on_client_hello_ptls}, listener}, + {{on_staple_ocsp_ptls}, ssl_config}}; + + { /* obtain key and cert (via fake connection for libressl compatibility) */ + SSL *fakeconn = SSL_new(ssl_ctx); + assert(fakeconn != NULL); + key = SSL_get_privatekey(fakeconn); + assert(key != NULL); + cert = SSL_get_certificate(fakeconn); + assert(cert != NULL); + SSL_free(fakeconn); + } + + if (ptls_openssl_init_sign_certificate(&pctx->sc, key) != 0) { + free(pctx); + return "failed to setup private key"; + } + + SSL_CTX_get_extra_chain_certs(ssl_ctx, &cert_chain); + ret = ptls_openssl_load_certificates(&pctx->ctx, cert, cert_chain); + assert(ret == 0); + + h2o_socket_ssl_set_picotls_context(ssl_ctx, &pctx->ctx); + + return NULL; +} + +#endif + +static void listener_setup_ssl_add_host(struct listener_ssl_config_t *ssl_config, h2o_iovec_t host) +{ + const char *host_end = memchr(host.base, ':', host.len); + if (host_end == NULL) + host_end = host.base + host.len; + + h2o_vector_reserve(NULL, &ssl_config->hostnames, ssl_config->hostnames.size + 1); + ssl_config->hostnames.entries[ssl_config->hostnames.size++] = h2o_iovec_init(host.base, host_end - host.base); +} + +static int listener_setup_ssl(h2o_configurator_command_t *cmd, h2o_configurator_context_t *ctx, yoml_t *listen_node, + yoml_t *ssl_node, struct listener_config_t *listener, int listener_is_new) +{ + SSL_CTX *ssl_ctx = NULL; + yoml_t *certificate_file = NULL, *key_file = NULL, *dh_file = NULL, *min_version = NULL, *max_version = NULL, + *cipher_suite = NULL, *ocsp_update_cmd = NULL, *ocsp_update_interval_node = NULL, *ocsp_max_failures_node = NULL; + long ssl_options = SSL_OP_ALL; + uint64_t ocsp_update_interval = 4 * 60 * 60; /* defaults to 4 hours */ + unsigned ocsp_max_failures = 3; /* defaults to 3; permit 3 failures before temporary disabling OCSP stapling */ + int use_neverbleed = 1, use_picotls = 1; /* enabled by default */ + + if (!listener_is_new) { + if (listener->ssl.size != 0 && ssl_node == NULL) { + h2o_configurator_errprintf(cmd, listen_node, "cannot accept HTTP; already defined to accept HTTPS"); + return -1; + } + if (listener->ssl.size == 0 && ssl_node != NULL) { + h2o_configurator_errprintf(cmd, ssl_node, "cannot accept HTTPS; already defined to accept HTTP"); + return -1; + } + } + + if (ssl_node == NULL) + return 0; + if (ssl_node->type != YOML_TYPE_MAPPING) { + h2o_configurator_errprintf(cmd, ssl_node, "`ssl` is not a mapping"); + return -1; + } + + { /* parse */ + size_t i; + for (i = 0; i != ssl_node->data.sequence.size; ++i) { + yoml_t *key = ssl_node->data.mapping.elements[i].key, *value = ssl_node->data.mapping.elements[i].value; + /* obtain the target command */ + if (key->type != YOML_TYPE_SCALAR) { + h2o_configurator_errprintf(NULL, key, "command must be a string"); + return -1; + } +#define FETCH_PROPERTY(n, p) \ + if (strcmp(key->data.scalar, n) == 0) { \ + if (value->type != YOML_TYPE_SCALAR) { \ + h2o_configurator_errprintf(cmd, value, "property of `" n "` must be a string"); \ + return -1; \ + } \ + p = value; \ + continue; \ + } + FETCH_PROPERTY("certificate-file", certificate_file); + FETCH_PROPERTY("key-file", key_file); + FETCH_PROPERTY("min-version", min_version); + FETCH_PROPERTY("minimum-version", min_version); + FETCH_PROPERTY("max-version", max_version); + FETCH_PROPERTY("maximum-version", max_version); + FETCH_PROPERTY("cipher-suite", cipher_suite); + FETCH_PROPERTY("ocsp-update-cmd", ocsp_update_cmd); + FETCH_PROPERTY("ocsp-update-interval", ocsp_update_interval_node); + FETCH_PROPERTY("ocsp-max-failures", ocsp_max_failures_node); + FETCH_PROPERTY("dh-file", dh_file); + if (strcmp(key->data.scalar, "cipher-preference") == 0) { + if (value->type == YOML_TYPE_SCALAR && strcasecmp(value->data.scalar, "client") == 0) { + ssl_options &= ~SSL_OP_CIPHER_SERVER_PREFERENCE; + } else if (value->type == YOML_TYPE_SCALAR && strcasecmp(value->data.scalar, "server") == 0) { + ssl_options |= SSL_OP_CIPHER_SERVER_PREFERENCE; + } else { + h2o_configurator_errprintf(cmd, value, "property of `cipher-preference` must be either of: `client`, `server`"); + return -1; + } + continue; + } + if (strcmp(key->data.scalar, "neverbleed") == 0) { + if (value->type == YOML_TYPE_SCALAR && strcasecmp(value->data.scalar, "ON") == 0) { + /* no need to enable neverbleed for daemon / master */ + use_neverbleed = 1; + } else if (value->type == YOML_TYPE_SCALAR && strcasecmp(value->data.scalar, "OFF") == 0) { + use_neverbleed = 0; + } else { + h2o_configurator_errprintf(cmd, value, "property of `neverbleed` must be either of: `ON`, `OFF"); + return -1; + } + continue; + } + h2o_configurator_errprintf(cmd, key, "unknown property: %s", key->data.scalar); + return -1; +#undef FETCH_PROPERTY + } + if (certificate_file == NULL) { + h2o_configurator_errprintf(cmd, ssl_node, "could not find mandatory property `certificate-file`"); + return -1; + } + if (key_file == NULL) { + h2o_configurator_errprintf(cmd, ssl_node, "could not find mandatory property `key-file`"); + return -1; + } + if (min_version != NULL) { +#define MAP(tok, op) \ + if (strcasecmp(min_version->data.scalar, tok) == 0) { \ + ssl_options |= (op); \ + goto VersionFound; \ + } + MAP("sslv2", 0); + MAP("sslv3", SSL_OP_NO_SSLv2); + MAP("tlsv1", SSL_OP_NO_SSLv2 | SSL_OP_NO_SSLv3); + MAP("tlsv1.1", SSL_OP_NO_SSLv2 | SSL_OP_NO_SSLv3 | SSL_OP_NO_TLSv1); +#ifdef SSL_OP_NO_TLSv1_1 + MAP("tlsv1.2", SSL_OP_NO_SSLv2 | SSL_OP_NO_SSLv3 | SSL_OP_NO_TLSv1 | SSL_OP_NO_TLSv1_1); +#endif +#ifdef SSL_OP_NO_TLSv1_2 + MAP("tlsv1.3", SSL_OP_NO_SSLv2 | SSL_OP_NO_SSLv3 | SSL_OP_NO_TLSv1 | SSL_OP_NO_TLSv1_1 | SSL_OP_NO_TLSv1_2); +#endif +#undef MAP + h2o_configurator_errprintf(cmd, min_version, "unknown protocol version: %s", min_version->data.scalar); + VersionFound:; + } else { + /* default is >= TLSv1 */ + ssl_options |= SSL_OP_NO_SSLv2 | SSL_OP_NO_SSLv3; + } + if (max_version != NULL) { + if (strcasecmp(max_version->data.scalar, "tlsv1.3") < 0) + use_picotls = 0; + } + if (ocsp_update_interval_node != NULL) { + if (h2o_configurator_scanf(cmd, ocsp_update_interval_node, "%" PRIu64, &ocsp_update_interval) != 0) + goto Error; + } + if (ocsp_max_failures_node != NULL) { + if (h2o_configurator_scanf(cmd, ocsp_max_failures_node, "%u", &ocsp_max_failures) != 0) + goto Error; + } + } + + /* add the host to the existing SSL config, if the certificate file is already registered */ + if (ctx->hostconf != NULL) { + size_t i; + for (i = 0; i != listener->ssl.size; ++i) { + struct listener_ssl_config_t *ssl_config = listener->ssl.entries[i]; + if (strcmp(ssl_config->certificate_file, certificate_file->data.scalar) == 0) { + listener_setup_ssl_add_host(ssl_config, ctx->hostconf->authority.hostport); + return 0; + } + } + } + +/* disable tls compression to avoid "CRIME" attacks (see http://en.wikipedia.org/wiki/CRIME) */ +#ifdef SSL_OP_NO_COMPRESSION + ssl_options |= SSL_OP_NO_COMPRESSION; +#endif + + /* setup */ + ssl_ctx = SSL_CTX_new(SSLv23_server_method()); + SSL_CTX_set_options(ssl_ctx, ssl_options); + + setup_ecc_key(ssl_ctx); + if (SSL_CTX_use_certificate_chain_file(ssl_ctx, certificate_file->data.scalar) != 1) { + h2o_configurator_errprintf(cmd, certificate_file, "failed to load certificate file:%s\n", certificate_file->data.scalar); + ERR_print_errors_cb(on_openssl_print_errors, stderr); + goto Error; + } + if (use_neverbleed) { + /* disable neverbleed in case the process is not going to serve requests */ + switch (conf.run_mode) { + case RUN_MODE_DAEMON: + case RUN_MODE_MASTER: + use_neverbleed = 0; + break; + default: + break; + } + } + if (use_neverbleed) { + char errbuf[NEVERBLEED_ERRBUF_SIZE]; + if (neverbleed == NULL) { + neverbleed = h2o_mem_alloc(sizeof(*neverbleed)); + if (neverbleed_init(neverbleed, errbuf) != 0) { + fprintf(stderr, "%s\n", errbuf); + abort(); + } + } + if (neverbleed_load_private_key_file(neverbleed, ssl_ctx, key_file->data.scalar, errbuf) != 1) { + h2o_configurator_errprintf(cmd, key_file, "failed to load private key file:%s:%s\n", key_file->data.scalar, errbuf); + goto Error; + } + } else { + if (SSL_CTX_use_PrivateKey_file(ssl_ctx, key_file->data.scalar, SSL_FILETYPE_PEM) != 1) { + h2o_configurator_errprintf(cmd, key_file, "failed to load private key file:%s\n", key_file->data.scalar); + ERR_print_errors_cb(on_openssl_print_errors, stderr); + goto Error; + } + } + if (cipher_suite != NULL && SSL_CTX_set_cipher_list(ssl_ctx, cipher_suite->data.scalar) != 1) { + h2o_configurator_errprintf(cmd, cipher_suite, "failed to setup SSL cipher suite\n"); + ERR_print_errors_cb(on_openssl_print_errors, stderr); + goto Error; + } + if (dh_file != NULL) { + BIO *bio = BIO_new_file(dh_file->data.scalar, "r"); + if (bio == NULL) { + h2o_configurator_errprintf(cmd, dh_file, "failed to load dhparam file:%s\n", dh_file->data.scalar); + ERR_print_errors_cb(on_openssl_print_errors, stderr); + goto Error; + } + DH *dh = PEM_read_bio_DHparams(bio, NULL, NULL, NULL); + BIO_free(bio); + if (dh == NULL) { + h2o_configurator_errprintf(cmd, dh_file, "failed to load dhparam file:%s\n", dh_file->data.scalar); + ERR_print_errors_cb(on_openssl_print_errors, stderr); + goto Error; + } + SSL_CTX_set_tmp_dh(ssl_ctx, dh); + SSL_CTX_set_options(ssl_ctx, SSL_OP_SINGLE_DH_USE); + DH_free(dh); + } + +/* setup protocol negotiation methods */ +#if H2O_USE_NPN + h2o_ssl_register_npn_protocols(ssl_ctx, h2o_npn_protocols); +#endif +#if H2O_USE_ALPN + h2o_ssl_register_alpn_protocols(ssl_ctx, h2o_alpn_protocols); +#endif + + /* set SNI callback to the first SSL context, when and only when it should be used */ + if (listener->ssl.size == 1) { + SSL_CTX_set_tlsext_servername_callback(listener->ssl.entries[0]->ctx, on_sni_callback); + SSL_CTX_set_tlsext_servername_arg(listener->ssl.entries[0]->ctx, listener); + } + + /* create a new entry in the SSL context list */ + struct listener_ssl_config_t *ssl_config = h2o_mem_alloc(sizeof(*ssl_config)); + memset(ssl_config, 0, sizeof(*ssl_config)); + h2o_vector_reserve(NULL, &listener->ssl, listener->ssl.size + 1); + listener->ssl.entries[listener->ssl.size++] = ssl_config; + if (ctx->hostconf != NULL) { + listener_setup_ssl_add_host(ssl_config, ctx->hostconf->authority.hostport); + } + ssl_config->ctx = ssl_ctx; + ssl_config->certificate_file = h2o_strdup(NULL, certificate_file->data.scalar, SIZE_MAX).base; + +#if !H2O_USE_OCSP + if (ocsp_update_interval != 0) + fprintf(stderr, "[OCSP Stapling] disabled (not support by the SSL library)\n"); +#else +#ifndef OPENSSL_NO_OCSP + SSL_CTX_set_tlsext_status_cb(ssl_ctx, on_staple_ocsp_ossl); + SSL_CTX_set_tlsext_status_arg(ssl_ctx, ssl_config); +#endif + pthread_mutex_init(&ssl_config->ocsp_stapling.response.mutex, NULL); + ssl_config->ocsp_stapling.cmd = + ocsp_update_cmd != NULL ? h2o_strdup(NULL, ocsp_update_cmd->data.scalar, SIZE_MAX).base : "share/h2o/fetch-ocsp-response"; + if (ocsp_update_interval != 0) { + switch (conf.run_mode) { + case RUN_MODE_WORKER: + ssl_config->ocsp_stapling.interval = + ocsp_update_interval; /* is also used as a flag for indicating if the updater thread was spawned */ + ssl_config->ocsp_stapling.max_failures = ocsp_max_failures; + h2o_multithread_create_thread(&ssl_config->ocsp_stapling.updater_tid, NULL, ocsp_updater_thread, ssl_config); + break; + case RUN_MODE_MASTER: + case RUN_MODE_DAEMON: + /* nothing to do */ + break; + case RUN_MODE_TEST: { + h2o_buffer_t *respbuf; + fprintf(stderr, "[OCSP Stapling] testing for certificate file:%s\n", certificate_file->data.scalar); + switch (get_ocsp_response(certificate_file->data.scalar, ssl_config->ocsp_stapling.cmd, &respbuf)) { + case 0: + h2o_buffer_dispose(&respbuf); + fprintf(stderr, "[OCSP Stapling] stapling works for file:%s\n", certificate_file->data.scalar); + break; + case EX_TEMPFAIL: + h2o_configurator_errprintf(cmd, certificate_file, "[OCSP Stapling] temporary failed for file:%s\n", + certificate_file->data.scalar); + break; + default: + h2o_configurator_errprintf(cmd, certificate_file, "[OCSP Stapling] does not work, will be disabled for file:%s\n", + certificate_file->data.scalar); + break; + } + } break; + } + } +#endif + +#if H2O_USE_PICOTLS + if (use_picotls) { + const char *errstr = listener_setup_ssl_picotls(listener, ssl_config, ssl_ctx); + if (errstr != NULL) + h2o_configurator_errprintf(cmd, ssl_node, "%s; TLS 1.3 will be disabled\n", errstr); + } +#endif + + return 0; + +Error: + if (ssl_ctx != NULL) + SSL_CTX_free(ssl_ctx); + return -1; +} + +static struct listener_config_t *find_listener(struct sockaddr *addr, socklen_t addrlen) +{ + size_t i; + + for (i = 0; i != conf.num_listeners; ++i) { + struct listener_config_t *listener = conf.listeners[i]; + if (listener->addrlen == addrlen && h2o_socket_compare_address((void *)&listener->addr, addr) == 0) + return listener; + } + + return NULL; +} + +static struct listener_config_t *add_listener(int fd, struct sockaddr *addr, socklen_t addrlen, int is_global, int proxy_protocol) +{ + struct listener_config_t *listener = h2o_mem_alloc(sizeof(*listener)); + + memcpy(&listener->addr, addr, addrlen); + listener->fd = fd; + listener->addrlen = addrlen; + if (is_global) { + listener->hosts = NULL; + } else { + listener->hosts = h2o_mem_alloc(sizeof(listener->hosts[0])); + listener->hosts[0] = NULL; + } + memset(&listener->ssl, 0, sizeof(listener->ssl)); + listener->proxy_protocol = proxy_protocol; + + conf.listeners = h2o_mem_realloc(conf.listeners, sizeof(*conf.listeners) * (conf.num_listeners + 1)); + conf.listeners[conf.num_listeners++] = listener; + + return listener; +} + +static int find_listener_from_server_starter(struct sockaddr *addr) +{ + size_t i; + + assert(conf.server_starter.fds != NULL); + assert(conf.server_starter.num_fds != 0); + + for (i = 0; i != conf.server_starter.num_fds; ++i) { + struct sockaddr_storage sa; + socklen_t salen = sizeof(sa); + if (getsockname(conf.server_starter.fds[i], (void *)&sa, &salen) != 0) { + fprintf(stderr, "could not get the socket address of fd %d given as $SERVER_STARTER_PORT\n", + conf.server_starter.fds[i]); + exit(EX_CONFIG); + } + if (h2o_socket_compare_address((void *)&sa, addr) == 0) + goto Found; + } + /* not found */ + return -1; + +Found: + conf.server_starter.bound_fd_map[i] = 1; + return conf.server_starter.fds[i]; +} + +static int open_unix_listener(h2o_configurator_command_t *cmd, yoml_t *node, struct sockaddr_un *sa) +{ + struct stat st; + int fd = -1; + struct passwd *owner = NULL, pwbuf; + char pwbuf_buf[65536]; + unsigned mode = UINT_MAX; + yoml_t *t; + + /* obtain owner and permission */ + if ((t = yoml_get(node, "owner")) != NULL) { + if (t->type != YOML_TYPE_SCALAR) { + h2o_configurator_errprintf(cmd, t, "`owner` is not a scalar"); + goto ErrorExit; + } + if (getpwnam_r(t->data.scalar, &pwbuf, pwbuf_buf, sizeof(pwbuf_buf), &owner) != 0 || owner == NULL) { + h2o_configurator_errprintf(cmd, t, "failed to obtain uid of user:%s: %s", t->data.scalar, strerror(errno)); + goto ErrorExit; + } + } + if ((t = yoml_get(node, "permission")) != NULL) { + if (t->type != YOML_TYPE_SCALAR || sscanf(t->data.scalar, "%o", &mode) != 1) { + h2o_configurator_errprintf(cmd, t, "`permission` must be an octal number"); + goto ErrorExit; + } + } + + /* remove existing socket file as suggested in #45 */ + if (lstat(sa->sun_path, &st) == 0) { + if (S_ISSOCK(st.st_mode)) { + unlink(sa->sun_path); + } else { + h2o_configurator_errprintf(cmd, node, "path:%s already exists and is not an unix socket.", sa->sun_path); + goto ErrorExit; + } + } + + /* add new listener */ + if ((fd = socket(AF_UNIX, SOCK_STREAM, 0)) == -1 || bind(fd, (void *)sa, sizeof(*sa)) != 0 || listen(fd, H2O_SOMAXCONN) != 0) { + h2o_configurator_errprintf(NULL, node, "failed to listen to socket:%s: %s", sa->sun_path, strerror(errno)); + goto ErrorExit; + } + set_cloexec(fd); + + /* set file owner and permission */ + if (owner != NULL && chown(sa->sun_path, owner->pw_uid, owner->pw_gid) != 0) { + h2o_configurator_errprintf(NULL, node, "failed to chown socket:%s to %s: %s", sa->sun_path, owner->pw_name, + strerror(errno)); + goto ErrorExit; + } + if (mode != UINT_MAX && chmod(sa->sun_path, mode) != 0) { + h2o_configurator_errprintf(NULL, node, "failed to chmod socket:%s to %o: %s", sa->sun_path, mode, strerror(errno)); + goto ErrorExit; + } + + return fd; + +ErrorExit: + if (fd != -1) + close(fd); + return -1; +} + +static int open_tcp_listener(h2o_configurator_command_t *cmd, yoml_t *node, const char *hostname, const char *servname, int domain, + int type, int protocol, struct sockaddr *addr, socklen_t addrlen) +{ + int fd; + + if ((fd = socket(domain, type, protocol)) == -1) + goto Error; + set_cloexec(fd); + { /* set reuseaddr */ + int flag = 1; + if (setsockopt(fd, SOL_SOCKET, SO_REUSEADDR, &flag, sizeof(flag)) != 0) + goto Error; + } +#ifdef TCP_DEFER_ACCEPT + { /* set TCP_DEFER_ACCEPT */ + int flag = 1; + if (setsockopt(fd, IPPROTO_TCP, TCP_DEFER_ACCEPT, &flag, sizeof(flag)) != 0) + goto Error; + } +#endif +#ifdef IPV6_V6ONLY + /* set IPv6only */ + if (domain == AF_INET6) { + int flag = 1; + if (setsockopt(fd, IPPROTO_IPV6, IPV6_V6ONLY, &flag, sizeof(flag)) != 0) + goto Error; + } +#endif + if (bind(fd, addr, addrlen) != 0) + goto Error; + if (listen(fd, H2O_SOMAXCONN) != 0) + goto Error; + + /* set TCP_FASTOPEN; when tfo_queues is zero TFO is always disabled */ + if (conf.tfo_queues > 0) { +#ifdef TCP_FASTOPEN + int tfo_queues; +#ifdef __APPLE__ + /* In OS X, the option value for TCP_FASTOPEN must be 1 if is's enabled */ + tfo_queues = 1; +#else + tfo_queues = conf.tfo_queues; +#endif + if (setsockopt(fd, IPPROTO_TCP, TCP_FASTOPEN, (const void *)&tfo_queues, sizeof(tfo_queues)) != 0) + fprintf(stderr, "[warning] failed to set TCP_FASTOPEN:%s\n", strerror(errno)); +#else + assert(!"conf.tfo_queues not zero on platform without TCP_FASTOPEN"); +#endif + } + + return fd; + +Error: + if (fd != -1) + close(fd); + h2o_configurator_errprintf(NULL, node, "failed to listen to port %s:%s: %s", hostname != NULL ? hostname : "ANY", servname, + strerror(errno)); + return -1; +} + +static int on_config_listen(h2o_configurator_command_t *cmd, h2o_configurator_context_t *ctx, yoml_t *node) +{ + const char *hostname = NULL, *servname = NULL, *type = "tcp"; + yoml_t *ssl_node = NULL; + int proxy_protocol = 0; + + /* fetch servname (and hostname) */ + switch (node->type) { + case YOML_TYPE_SCALAR: + servname = node->data.scalar; + break; + case YOML_TYPE_MAPPING: { + yoml_t *t; + if ((t = yoml_get(node, "host")) != NULL) { + if (t->type != YOML_TYPE_SCALAR) { + h2o_configurator_errprintf(cmd, t, "`host` is not a string"); + return -1; + } + hostname = t->data.scalar; + } + if ((t = yoml_get(node, "port")) == NULL) { + h2o_configurator_errprintf(cmd, node, "cannot find mandatory property `port`"); + return -1; + } + if (t->type != YOML_TYPE_SCALAR) { + h2o_configurator_errprintf(cmd, node, "`port` is not a string"); + return -1; + } + servname = t->data.scalar; + if ((t = yoml_get(node, "type")) != NULL) { + if (t->type != YOML_TYPE_SCALAR) { + h2o_configurator_errprintf(cmd, t, "`type` is not a string"); + return -1; + } + type = t->data.scalar; + } + if ((t = yoml_get(node, "ssl")) != NULL) + ssl_node = t; + if ((t = yoml_get(node, "proxy-protocol")) != NULL) { + if (t->type != YOML_TYPE_SCALAR) { + h2o_configurator_errprintf(cmd, node, "`proxy-protocol` must be a string"); + return -1; + } + if (strcasecmp(t->data.scalar, "ON") == 0) { + proxy_protocol = 1; + } else if (strcasecmp(t->data.scalar, "OFF") == 0) { + proxy_protocol = 0; + } else { + h2o_configurator_errprintf(cmd, node, "value of `proxy-protocol` must be either of: ON,OFF"); + return -1; + } + } + } break; + default: + h2o_configurator_errprintf(cmd, node, "value must be a string or a mapping (with keys: `port` and optionally `host`)"); + return -1; + } + + if (strcmp(type, "unix") == 0) { + + /* unix socket */ + struct sockaddr_un sa; + int listener_is_new; + struct listener_config_t *listener; + /* build sockaddr */ + memset(&sa, 0, sizeof(sa)); + if (strlen(servname) >= sizeof(sa.sun_path)) { + h2o_configurator_errprintf(cmd, node, "path:%s is too long as a unix socket name", servname); + return -1; + } + sa.sun_family = AF_UNIX; + strcpy(sa.sun_path, servname); + /* find existing listener or create a new one */ + listener_is_new = 0; + if ((listener = find_listener((void *)&sa, sizeof(sa))) == NULL) { + int fd = -1; + switch (conf.run_mode) { + case RUN_MODE_WORKER: + if (conf.server_starter.fds != NULL) { + if ((fd = find_listener_from_server_starter((void *)&sa)) == -1) { + h2o_configurator_errprintf(cmd, node, "unix socket:%s is not being bound to the server\n", sa.sun_path); + return -1; + } + } else { + if ((fd = open_unix_listener(cmd, node, &sa)) == -1) + return -1; + } + break; + default: + break; + } + listener = add_listener(fd, (struct sockaddr *)&sa, sizeof(sa), ctx->hostconf == NULL, proxy_protocol); + listener_is_new = 1; + } else if (listener->proxy_protocol != proxy_protocol) { + goto ProxyConflict; + } + if (listener_setup_ssl(cmd, ctx, node, ssl_node, listener, listener_is_new) != 0) + return -1; + if (listener->hosts != NULL && ctx->hostconf != NULL) + h2o_append_to_null_terminated_list((void *)&listener->hosts, ctx->hostconf); + + } else if (strcmp(type, "tcp") == 0) { + + /* TCP socket */ + struct addrinfo hints, *res, *ai; + int error; + /* call getaddrinfo */ + memset(&hints, 0, sizeof(hints)); + hints.ai_socktype = SOCK_STREAM; + hints.ai_protocol = IPPROTO_TCP; + hints.ai_flags = AI_ADDRCONFIG | AI_NUMERICSERV | AI_PASSIVE; + if ((error = getaddrinfo(hostname, servname, &hints, &res)) != 0) { + h2o_configurator_errprintf(cmd, node, "failed to resolve the listening address: %s", gai_strerror(error)); + return -1; + } else if (res == NULL) { + h2o_configurator_errprintf(cmd, node, "failed to resolve the listening address: getaddrinfo returned an empty list"); + return -1; + } + /* listen to the returned addresses */ + for (ai = res; ai != NULL; ai = ai->ai_next) { + struct listener_config_t *listener = find_listener(ai->ai_addr, ai->ai_addrlen); + int listener_is_new = 0; + if (listener == NULL) { + int fd = -1; + switch (conf.run_mode) { + case RUN_MODE_WORKER: + if (conf.server_starter.fds != NULL) { + if ((fd = find_listener_from_server_starter(ai->ai_addr)) == -1) { + h2o_configurator_errprintf(cmd, node, "tcp socket:%s:%s is not being bound to the server\n", hostname, + servname); + freeaddrinfo(res); + return -1; + } + } else { + if ((fd = open_tcp_listener(cmd, node, hostname, servname, ai->ai_family, ai->ai_socktype, ai->ai_protocol, + ai->ai_addr, ai->ai_addrlen)) == -1) { + freeaddrinfo(res); + return -1; + } + } + break; + default: + break; + } + listener = add_listener(fd, ai->ai_addr, ai->ai_addrlen, ctx->hostconf == NULL, proxy_protocol); + listener_is_new = 1; + } else if (listener->proxy_protocol != proxy_protocol) { + freeaddrinfo(res); + goto ProxyConflict; + } + if (listener_setup_ssl(cmd, ctx, node, ssl_node, listener, listener_is_new) != 0) { + freeaddrinfo(res); + return -1; + } + if (listener->hosts != NULL && ctx->hostconf != NULL) + h2o_append_to_null_terminated_list((void *)&listener->hosts, ctx->hostconf); + } + /* release res */ + freeaddrinfo(res); + + } else { + + h2o_configurator_errprintf(cmd, node, "unknown listen type: %s", type); + return -1; + } + + return 0; + +ProxyConflict: + h2o_configurator_errprintf(cmd, node, "`proxy-protocol` cannot be turned %s, already defined as opposite", + proxy_protocol ? "on" : "off"); + return -1; +} + +static int on_config_listen_enter(h2o_configurator_t *_configurator, h2o_configurator_context_t *ctx, yoml_t *node) +{ + return 0; +} + +static int on_config_listen_exit(h2o_configurator_t *_configurator, h2o_configurator_context_t *ctx, yoml_t *node) +{ + if (ctx->pathconf != NULL) { + /* skip */ + } else if (ctx->hostconf == NULL) { + /* at global level: bind all hostconfs to the global-level listeners */ + size_t i; + for (i = 0; i != conf.num_listeners; ++i) { + struct listener_config_t *listener = conf.listeners[i]; + if (listener->hosts == NULL) + listener->hosts = conf.globalconf.hosts; + } + } else if (ctx->pathconf == NULL) { + /* at host-level */ + if (conf.num_listeners == 0) { + h2o_configurator_errprintf( + NULL, node, + "mandatory configuration directive `listen` does not exist, neither at global level or at this host level"); + return -1; + } + } + + return 0; +} + +static int on_config_user(h2o_configurator_command_t *cmd, h2o_configurator_context_t *ctx, yoml_t *node) +{ + errno = 0; + if (getpwnam(node->data.scalar) == NULL) { + if (errno == 0) { + h2o_configurator_errprintf(cmd, node, "user:%s does not exist", node->data.scalar); + } else { + perror("getpwnam"); + } + return -1; + } + ctx->globalconf->user = h2o_strdup(NULL, node->data.scalar, SIZE_MAX).base; + return 0; +} + +static int on_config_pid_file(h2o_configurator_command_t *cmd, h2o_configurator_context_t *ctx, yoml_t *node) +{ + conf.pid_file = h2o_strdup(NULL, node->data.scalar, SIZE_MAX).base; + return 0; +} + +static int on_config_error_log(h2o_configurator_command_t *cmd, h2o_configurator_context_t *ctx, yoml_t *node) +{ + conf.error_log = h2o_strdup(NULL, node->data.scalar, SIZE_MAX).base; + return 0; +} + +static int on_config_max_connections(h2o_configurator_command_t *cmd, h2o_configurator_context_t *ctx, yoml_t *node) +{ + return h2o_configurator_scanf(cmd, node, "%d", &conf.max_connections); +} + +static int on_config_num_threads(h2o_configurator_command_t *cmd, h2o_configurator_context_t *ctx, yoml_t *node) +{ + if (h2o_configurator_scanf(cmd, node, "%zu", &conf.num_threads) != 0) + return -1; + if (conf.num_threads == 0) { + h2o_configurator_errprintf(cmd, node, "num-threads must be >=1"); + return -1; + } + return 0; +} + +static int on_config_num_name_resolution_threads(h2o_configurator_command_t *cmd, h2o_configurator_context_t *ctx, yoml_t *node) +{ + if (h2o_configurator_scanf(cmd, node, "%zu", &h2o_hostinfo_max_threads) != 0) + return -1; + if (h2o_hostinfo_max_threads == 0) { + h2o_configurator_errprintf(cmd, node, "num-name-resolution-threads must be >=1"); + return -1; + } + return 0; +} + +static int on_config_tcp_fastopen(h2o_configurator_command_t *cmd, h2o_configurator_context_t *ctx, yoml_t *node) +{ + if (h2o_configurator_scanf(cmd, node, "%d", &conf.tfo_queues) != 0) + return -1; +#ifndef TCP_FASTOPEN + if (conf.tfo_queues != 0) { + h2o_configurator_errprintf(cmd, node, "[warning] ignoring the value; the platform does not support TCP_FASTOPEN"); + conf.tfo_queues = 0; + } +#endif + return 0; +} + +static int on_config_num_ocsp_updaters(h2o_configurator_command_t *cmd, h2o_configurator_context_t *ctx, yoml_t *node) +{ + ssize_t n; + if (h2o_configurator_scanf(cmd, node, "%zd", &n) != 0) + return -1; + if (n <= 0) { + h2o_configurator_errprintf(cmd, node, "num-ocsp-updaters must be >=1"); + return -1; + } + h2o_sem_set_capacity(&ocsp_updater_semaphore, n); + return 0; +} + +static int on_config_temp_buffer_path(h2o_configurator_command_t *cmd, h2o_configurator_context_t *ctx, yoml_t *node) +{ + char buf[sizeof(h2o_socket_buffer_mmap_settings.fn_template)]; + + int len = snprintf(buf, sizeof(buf), "%s%s", node->data.scalar, strrchr(h2o_socket_buffer_mmap_settings.fn_template, '/')); + if (len >= sizeof(buf)) { + h2o_configurator_errprintf(cmd, node, "path is too long"); + return -1; + } + strcpy(h2o_socket_buffer_mmap_settings.fn_template, buf); + + return 0; +} + +static int on_config_crash_handler(h2o_configurator_command_t *cmd, h2o_configurator_context_t *ctx, yoml_t *node) +{ + conf.crash_handler = h2o_strdup(NULL, node->data.scalar, SIZE_MAX).base; + return 0; +} + +static int on_config_crash_handler_wait_pipe_close(h2o_configurator_command_t *cmd, h2o_configurator_context_t *ctx, yoml_t *node) +{ + ssize_t v; + + if ((v = h2o_configurator_get_one_of(cmd, node, "OFF,ON")) == -1) + return -1; + + conf.crash_handler_wait_pipe_close = (int)v; + return 0; +} + +static yoml_t *load_config(yoml_parse_args_t *parse_args, yoml_t *source) +{ + FILE *fp; + yaml_parser_t parser; + yoml_t *yoml; + + if ((fp = fopen(parse_args->filename, "rb")) == NULL) { + fprintf(stderr, "could not open configuration file %s: %s\n", parse_args->filename, strerror(errno)); + return NULL; + } + + yaml_parser_initialize(&parser); + yaml_parser_set_input_file(&parser, fp); + + yoml = yoml_parse_document(&parser, NULL, parse_args); + + if (yoml == NULL) { + fprintf(stderr, "failed to parse configuration file %s line %d", parse_args->filename, (int)parser.problem_mark.line + 1); + if (source != NULL) { + fprintf(stderr, " (included from file %s line %d)", source->filename, (int)source->line + 1); + } + fprintf(stderr, ": %s\n", parser.problem); + } + + yaml_parser_delete(&parser); + + fclose(fp); + + return yoml; +} + +static yoml_t *resolve_tag(const char *tag, yoml_t *node, void *cb_arg); +static yoml_t *resolve_file_tag(yoml_t *node, resolve_tag_arg_t *arg) +{ + size_t i; + yoml_t *loaded; + + if (node->type != YOML_TYPE_SCALAR) { + fprintf(stderr, "value of the !file node must be a scalar"); + return NULL; + } + + char *filename = node->data.scalar; + + /* check cache */ + for (i = 0; i != arg->node_cache.size; ++i) { + resolve_tag_node_cache_entry_t *cached = arg->node_cache.entries + i; + if (strcmp(filename, cached->filename.base) == 0) { + ++cached->node->_refcnt; + return cached->node; + } + } + + yoml_parse_args_t parse_args = { + filename, /* filename */ + NULL, /* mem_set */ + {resolve_tag, arg} /* resolve_tag */ + }; + loaded = load_config(&parse_args, node); + + if (loaded != NULL) { + /* cache newly loaded node */ + h2o_vector_reserve(NULL, &arg->node_cache, arg->node_cache.size + 1); + resolve_tag_node_cache_entry_t entry = {h2o_strdup(NULL, filename, SIZE_MAX), loaded}; + arg->node_cache.entries[arg->node_cache.size++] = entry; + ++loaded->_refcnt; + } + + return loaded; +} + +static yoml_t *resolve_tag(const char *tag, yoml_t *node, void *cb_arg) +{ + resolve_tag_arg_t *arg = (resolve_tag_arg_t *)cb_arg; + + if (strcmp(tag, "!file") == 0) { + return resolve_file_tag(node, arg); + } + + /* otherwise, return the node itself */ + ++node->_refcnt; + return node; +} + +static void dispose_resolve_tag_arg(resolve_tag_arg_t *arg) +{ + size_t i; + for (i = 0; i != arg->node_cache.size; ++i) { + resolve_tag_node_cache_entry_t *cached = arg->node_cache.entries + i; + free(cached->filename.base); + yoml_free(cached->node, NULL); + } + free(arg->node_cache.entries); +} + +static void notify_all_threads(void) +{ + unsigned i; + for (i = 0; i != conf.num_threads; ++i) + h2o_multithread_send_message(&conf.threads[i].server_notifications, NULL); +} + +static void on_sigterm(int signo) +{ + conf.shutdown_requested = 1; + if (!h2o_barrier_done(&conf.startup_sync_barrier)) { + /* initialization hasn't completed yet, exit right away */ + exit(0); + } + notify_all_threads(); +} + +#ifdef __GLIBC__ +static int popen_crash_handler(void) +{ + char *cmd_fullpath = h2o_configurator_get_cmd_path(conf.crash_handler), *argv[] = {cmd_fullpath, NULL}; + int pipefds[2]; + + /* create pipe */ + if (pipe(pipefds) != 0) { + perror("pipe failed"); + return -1; + } + if (fcntl(pipefds[1], F_SETFD, FD_CLOEXEC) == -1) { + perror("failed to set FD_CLOEXEC on pipefds[1]"); + return -1; + } + /* spawn the logger */ + int mapped_fds[] = {pipefds[0], 0, /* output of the pipe is connected to STDIN of the spawned process */ + 2, 1, /* STDOUT of the spawned process in connected to STDERR of h2o */ + -1}; + if (h2o_spawnp(cmd_fullpath, argv, mapped_fds, 0) == -1) { + /* silently ignore error */ + close(pipefds[0]); + close(pipefds[1]); + return -1; + } + /* do the rest, and return the fd */ + close(pipefds[0]); + return pipefds[1]; +} + +static int crash_handler_fd = -1; + +static void on_sigfatal(int signo) +{ + fprintf(stderr, "received fatal signal %d\n", signo); + + h2o_set_signal_handler(signo, SIG_DFL); + + void *frames[128]; + int framecnt = backtrace(frames, sizeof(frames) / sizeof(frames[0])); + backtrace_symbols_fd(frames, framecnt, crash_handler_fd); + + if (conf.crash_handler_wait_pipe_close) { + struct pollfd pfd[1]; + pfd[0].fd = crash_handler_fd; + pfd[0].events = POLLERR | POLLHUP; + while (poll(pfd, 1, -1) == -1 && errno == EINTR) + ; + } + + raise(signo); +} +#endif + +static void setup_signal_handlers(void) +{ + h2o_set_signal_handler(SIGTERM, on_sigterm); + h2o_set_signal_handler(SIGPIPE, SIG_IGN); +#ifdef __GLIBC__ + if ((crash_handler_fd = popen_crash_handler()) == -1) + crash_handler_fd = 2; + h2o_set_signal_handler(SIGABRT, on_sigfatal); + h2o_set_signal_handler(SIGBUS, on_sigfatal); + h2o_set_signal_handler(SIGFPE, on_sigfatal); + h2o_set_signal_handler(SIGILL, on_sigfatal); + h2o_set_signal_handler(SIGSEGV, on_sigfatal); +#endif +} + +static int num_connections(int delta) +{ + return __sync_fetch_and_add(&conf.state._num_connections, delta); +} + +static unsigned long num_sessions(int delta) +{ + return __sync_fetch_and_add(&conf.state._num_sessions, delta); +} + +static void on_socketclose(void *data) +{ + int prev_num_connections = num_connections(-1); + + if (prev_num_connections == conf.max_connections) { + /* ready to accept new connections. wake up all the threads! */ + notify_all_threads(); + } +} + +static void on_accept(h2o_socket_t *listener, const char *err) +{ + struct listener_ctx_t *ctx = listener->data; + size_t num_accepts = conf.max_connections / 16 / conf.num_threads; + if (num_accepts < 8) + num_accepts = 8; + + if (err != NULL) { + return; + } + + do { + h2o_socket_t *sock; + if (num_connections(0) >= conf.max_connections) { + /* The accepting socket is disactivated before entering the next in `run_loop`. + * Note: it is possible that the server would accept at most `max_connections + num_threads` connections, since the + * server does not check if the number of connections has exceeded _after_ epoll notifies of a new connection _but_ + * _before_ calling `accept`. In other words t/40max-connections.t may fail. + */ + break; + } + if ((sock = h2o_evloop_socket_accept(listener)) == NULL) { + break; + } + num_connections(1); + num_sessions(1); + + sock->on_close.cb = on_socketclose; + sock->on_close.data = ctx->accept_ctx.ctx; + + h2o_accept(&ctx->accept_ctx, sock); + + } while (--num_accepts != 0); +} + +static void update_listener_state(struct listener_ctx_t *listeners) +{ + size_t i; + + if (num_connections(0) < conf.max_connections) { + for (i = 0; i != conf.num_listeners; ++i) { + if (!h2o_socket_is_reading(listeners[i].sock)) + h2o_socket_read_start(listeners[i].sock, on_accept); + } + } else { + for (i = 0; i != conf.num_listeners; ++i) { + if (h2o_socket_is_reading(listeners[i].sock)) + h2o_socket_read_stop(listeners[i].sock); + } + } +} + +static void on_server_notification(h2o_multithread_receiver_t *receiver, h2o_linklist_t *messages) +{ + /* the notification is used only for exitting h2o_evloop_run; actual changes are done in the main loop of run_loop */ + + while (!h2o_linklist_is_empty(messages)) { + h2o_multithread_message_t *message = H2O_STRUCT_FROM_MEMBER(h2o_multithread_message_t, link, messages->next); + h2o_linklist_unlink(&message->link); + free(message); + } +} + +H2O_NORETURN static void *run_loop(void *_thread_index) +{ + size_t thread_index = (size_t)_thread_index; + struct listener_ctx_t *listeners = alloca(sizeof(*listeners) * conf.num_listeners); + size_t i; + + h2o_context_init(&conf.threads[thread_index].ctx, h2o_evloop_create(), &conf.globalconf); + h2o_multithread_register_receiver(conf.threads[thread_index].ctx.queue, &conf.threads[thread_index].server_notifications, + on_server_notification); + h2o_multithread_register_receiver(conf.threads[thread_index].ctx.queue, &conf.threads[thread_index].memcached, + h2o_memcached_receiver); + conf.threads[thread_index].tid = pthread_self(); + + /* setup listeners */ + for (i = 0; i != conf.num_listeners; ++i) { + struct listener_config_t *listener_config = conf.listeners[i]; + int fd; + /* dup the listener fd for other threads than the main thread */ + if (thread_index == 0) { + fd = listener_config->fd; + } else { + if ((fd = dup(listener_config->fd)) == -1) { + perror("failed to dup listening socket"); + abort(); + } + set_cloexec(fd); + } + memset(listeners + i, 0, sizeof(listeners[i])); + listeners[i].accept_ctx.ctx = &conf.threads[thread_index].ctx; + listeners[i].accept_ctx.hosts = listener_config->hosts; + if (listener_config->ssl.size != 0) + listeners[i].accept_ctx.ssl_ctx = listener_config->ssl.entries[0]->ctx; + listeners[i].accept_ctx.expect_proxy_line = listener_config->proxy_protocol; + listeners[i].accept_ctx.libmemcached_receiver = &conf.threads[thread_index].memcached; + listeners[i].sock = h2o_evloop_socket_create(conf.threads[thread_index].ctx.loop, fd, H2O_SOCKET_FLAG_DONT_READ); + listeners[i].sock->data = listeners + i; + } + /* and start listening */ + update_listener_state(listeners); + + /* make sure all threads are initialized before starting to serve requests */ + h2o_barrier_wait(&conf.startup_sync_barrier); + + /* the main loop */ + while (1) { + if (conf.shutdown_requested) + break; + update_listener_state(listeners); + /* run the loop once */ + h2o_evloop_run(conf.threads[thread_index].ctx.loop, INT32_MAX); + h2o_filecache_clear(conf.threads[thread_index].ctx.filecache); + } + + if (thread_index == 0) + fprintf(stderr, "received SIGTERM, gracefully shutting down\n"); + + /* shutdown requested, unregister, close the listeners and notify the protocol handlers */ + for (i = 0; i != conf.num_listeners; ++i) + h2o_socket_read_stop(listeners[i].sock); + h2o_evloop_run(conf.threads[thread_index].ctx.loop, 0); + for (i = 0; i != conf.num_listeners; ++i) { + h2o_socket_close(listeners[i].sock); + listeners[i].sock = NULL; + } + h2o_context_request_shutdown(&conf.threads[thread_index].ctx); + + /* wait until all the connection gets closed */ + while (num_connections(0) != 0) + h2o_evloop_run(conf.threads[thread_index].ctx.loop, INT32_MAX); + + /* the process that detects num_connections becoming zero performs the last cleanup */ + if (conf.pid_file != NULL) + unlink(conf.pid_file); + _exit(0); +} + +static char **build_server_starter_argv(const char *h2o_cmd, const char *config_file) +{ + H2O_VECTOR(char *) args = {NULL}; + size_t i; + + h2o_vector_reserve(NULL, &args, 1); + args.entries[args.size++] = h2o_configurator_get_cmd_path("share/h2o/start_server"); + + /* error-log and pid-file are the directives that are handled by server-starter */ + if (conf.pid_file != NULL) { + h2o_vector_reserve(NULL, &args, args.size + 1); + args.entries[args.size++] = + h2o_concat(NULL, h2o_iovec_init(H2O_STRLIT("--pid-file=")), h2o_iovec_init(conf.pid_file, strlen(conf.pid_file))).base; + } + if (conf.error_log != NULL) { + h2o_vector_reserve(NULL, &args, args.size + 1); + args.entries[args.size++] = + h2o_concat(NULL, h2o_iovec_init(H2O_STRLIT("--log-file=")), h2o_iovec_init(conf.error_log, strlen(conf.error_log))) + .base; + } + + switch (conf.run_mode) { + case RUN_MODE_DAEMON: + h2o_vector_reserve(NULL, &args, args.size + 1); + args.entries[args.size++] = "--daemonize"; + break; + default: + break; + } + + for (i = 0; i != conf.num_listeners; ++i) { + char *newarg; + switch (conf.listeners[i]->addr.ss_family) { + default: { + char host[NI_MAXHOST], serv[NI_MAXSERV]; + int err; + if ((err = getnameinfo((void *)&conf.listeners[i]->addr, conf.listeners[i]->addrlen, host, sizeof(host), serv, + sizeof(serv), NI_NUMERICHOST | NI_NUMERICSERV)) != 0) { + fprintf(stderr, "failed to stringify the address of %zu-th listen directive:%s\n", i, gai_strerror(err)); + exit(EX_OSERR); + } + newarg = h2o_mem_alloc(sizeof("--port=[]:") + strlen(host) + strlen(serv)); + if (strchr(host, ':') != NULL) { + sprintf(newarg, "--port=[%s]:%s", host, serv); + } else { + sprintf(newarg, "--port=%s:%s", host, serv); + } + } break; + case AF_UNIX: { + struct sockaddr_un *sa = (void *)&conf.listeners[i]->addr; + newarg = h2o_mem_alloc(sizeof("--path=") + strlen(sa->sun_path)); + sprintf(newarg, "--path=%s", sa->sun_path); + } break; + } + h2o_vector_reserve(NULL, &args, args.size + 1); + args.entries[args.size++] = newarg; + } + + h2o_vector_reserve(NULL, &args, args.size + 5); + args.entries[args.size++] = "--"; + args.entries[args.size++] = (char *)h2o_cmd; + args.entries[args.size++] = "-c"; + args.entries[args.size++] = (char *)config_file; + args.entries[args.size] = NULL; + + return args.entries; +} + +static int run_using_server_starter(const char *h2o_cmd, const char *config_file) +{ + char **args = build_server_starter_argv(h2o_cmd, config_file); + setenv("H2O_VIA_MASTER", "", 1); + execvp(args[0], args); + fprintf(stderr, "failed to spawn %s:%s\n", args[0], strerror(errno)); + return EX_CONFIG; +} + +/* make jemalloc linkage optional by marking the functions as 'weak', + * since upstream doesn't rely on it. */ +struct extra_status_jemalloc_cb_arg { + h2o_iovec_t outbuf; + int err; + size_t written; +}; + +#if JEMALLOC_STATS == 1 +static void extra_status_jemalloc_cb(void *ctx, const char *stats) +{ + size_t cur_len; + struct extra_status_jemalloc_cb_arg *out = ctx; + h2o_iovec_t outbuf = out->outbuf; + int i; + + if (out->written >= out->outbuf.len || out->err) { + return; + } + cur_len = out->written; + + i = 0; + while (cur_len < outbuf.len && stats[i]) { + switch (stats[i]) { +#define JSON_ESCAPE(x, y) \ + case x: \ + outbuf.base[cur_len++] = '\\'; \ + if (cur_len >= outbuf.len) { \ + goto err; \ + } \ + outbuf.base[cur_len] = y; \ + break; + JSON_ESCAPE('\b', 'b'); + JSON_ESCAPE('\f', 'f'); + JSON_ESCAPE('\n', 'n'); + JSON_ESCAPE('\r', 'r') + JSON_ESCAPE('\t', 't'); + JSON_ESCAPE('/', '/'); + JSON_ESCAPE('"', '"'); + JSON_ESCAPE('\\', '\\'); +#undef JSON_ESCAPE + default: + outbuf.base[cur_len] = stats[i]; + } + i++; + cur_len++; + } + if (cur_len < outbuf.len) { + out->written = cur_len; + return; + } + +err: + out->err = 1; + return; +} +#endif + +static h2o_iovec_t on_extra_status(void *unused, h2o_globalconf_t *_conf, h2o_req_t *req) +{ +#define BUFSIZE (16 * 1024) + h2o_iovec_t ret; + char current_time[H2O_TIMESTR_LOG_LEN + 1], restart_time[H2O_TIMESTR_LOG_LEN + 1]; + const char *generation; + time_t now = time(NULL); + + h2o_time2str_log(current_time, now); + h2o_time2str_log(restart_time, conf.launch_time); + if ((generation = getenv("SERVER_STARTER_GENERATION")) == NULL) + generation = "null"; + + ret.base = h2o_mem_alloc_pool(&req->pool, BUFSIZE); + ret.len = snprintf(ret.base, BUFSIZE, ",\n" + " \"server-version\": \"" H2O_VERSION "\",\n" + " \"openssl-version\": \"%s\",\n" + " \"current-time\": \"%s\",\n" + " \"restart-time\": \"%s\",\n" + " \"uptime\": %" PRIu64 ",\n" + " \"generation\": %s,\n" + " \"connections\": %d,\n" + " \"max-connections\": %d,\n" + " \"listeners\": %zu,\n" + " \"worker-threads\": %zu,\n" + " \"num-sessions\": %lu", + SSLeay_version(SSLEAY_VERSION), current_time, restart_time, (uint64_t)(now - conf.launch_time), generation, + num_connections(0), conf.max_connections, conf.num_listeners, conf.num_threads, num_sessions(0)); + assert(ret.len < BUFSIZE); + +#if JEMALLOC_STATS == 1 + struct extra_status_jemalloc_cb_arg arg; + size_t sz, allocated, active, metadata, resident, mapped; + uint64_t epoch = 1; + /* internal jemalloc interface */ + void malloc_stats_print(void (*write_cb)(void *, const char *), void *cbopaque, const char *opts); + int mallctl(const char *name, void *oldp, size_t *oldlenp, void *newp, size_t newlen); + + arg.outbuf = h2o_iovec_init(alloca(BUFSIZE - ret.len), BUFSIZE - ret.len); + arg.err = 0; + arg.written = snprintf(arg.outbuf.base, arg.outbuf.len, ",\n" + " \"jemalloc\": {\n" + " \"jemalloc-raw\": \""); + malloc_stats_print(extra_status_jemalloc_cb, &arg, "ga" /* omit general info, only aggregated stats */); + + if (arg.err || arg.written + 1 >= arg.outbuf.len) { + goto jemalloc_err; + } + + /* terminate the jemalloc-raw json string */ + arg.written += snprintf(&arg.outbuf.base[arg.written], arg.outbuf.len - arg.written, "\""); + if (arg.written + 1 >= arg.outbuf.len) { + goto jemalloc_err; + } + + sz = sizeof(epoch); + mallctl("epoch", &epoch, &sz, &epoch, sz); + + sz = sizeof(size_t); + if (!mallctl("stats.allocated", &allocated, &sz, NULL, 0) && !mallctl("stats.active", &active, &sz, NULL, 0) && + !mallctl("stats.metadata", &metadata, &sz, NULL, 0) && !mallctl("stats.resident", &resident, &sz, NULL, 0) && + !mallctl("stats.mapped", &mapped, &sz, NULL, 0)) { + arg.written += snprintf(&arg.outbuf.base[arg.written], arg.outbuf.len - arg.written, ",\n" + " \"allocated\": %zu,\n" + " \"active\": %zu,\n" + " \"metadata\": %zu,\n" + " \"resident\": %zu,\n" + " \"mapped\": %zu }", + allocated, active, metadata, resident, mapped); + } + if (arg.written + 1 >= arg.outbuf.len) { + goto jemalloc_err; + } + + strncpy(&ret.base[ret.len], arg.outbuf.base, arg.written); + ret.base[ret.len + arg.written] = '\0'; + ret.len += arg.written; + return ret; + +jemalloc_err: + /* couldn't fit the jemalloc output, exiting */ + ret.base[ret.len] = '\0'; + +#endif /* JEMALLOC_STATS == 1 */ + + return ret; +#undef BUFSIZE +} + +static void setup_configurators(void) +{ + h2o_config_init(&conf.globalconf); + + /* let the default setuid user be "nobody", if run as root */ + if (getuid() == 0 && getpwnam("nobody") != NULL) + conf.globalconf.user = "nobody"; + + { + h2o_configurator_t *c = h2o_configurator_create(&conf.globalconf, sizeof(*c)); + c->enter = on_config_listen_enter; + c->exit = on_config_listen_exit; + h2o_configurator_define_command(c, "listen", H2O_CONFIGURATOR_FLAG_GLOBAL | H2O_CONFIGURATOR_FLAG_HOST, on_config_listen); + } + + { + h2o_configurator_t *c = h2o_configurator_create(&conf.globalconf, sizeof(*c)); + h2o_configurator_define_command(c, "user", H2O_CONFIGURATOR_FLAG_GLOBAL | H2O_CONFIGURATOR_FLAG_EXPECT_SCALAR, + on_config_user); + h2o_configurator_define_command(c, "pid-file", H2O_CONFIGURATOR_FLAG_GLOBAL | H2O_CONFIGURATOR_FLAG_EXPECT_SCALAR, + on_config_pid_file); + h2o_configurator_define_command(c, "error-log", H2O_CONFIGURATOR_FLAG_GLOBAL | H2O_CONFIGURATOR_FLAG_EXPECT_SCALAR, + on_config_error_log); + h2o_configurator_define_command(c, "max-connections", H2O_CONFIGURATOR_FLAG_GLOBAL, on_config_max_connections); + h2o_configurator_define_command(c, "num-threads", H2O_CONFIGURATOR_FLAG_GLOBAL, on_config_num_threads); + h2o_configurator_define_command(c, "num-name-resolution-threads", H2O_CONFIGURATOR_FLAG_GLOBAL, + on_config_num_name_resolution_threads); + h2o_configurator_define_command(c, "tcp-fastopen", H2O_CONFIGURATOR_FLAG_GLOBAL, on_config_tcp_fastopen); + h2o_configurator_define_command(c, "ssl-session-resumption", + H2O_CONFIGURATOR_FLAG_GLOBAL | H2O_CONFIGURATOR_FLAG_EXPECT_MAPPING, + ssl_session_resumption_on_config); + h2o_configurator_define_command(c, "num-ocsp-updaters", H2O_CONFIGURATOR_FLAG_GLOBAL | H2O_CONFIGURATOR_FLAG_EXPECT_SCALAR, + on_config_num_ocsp_updaters); + h2o_configurator_define_command(c, "temp-buffer-path", H2O_CONFIGURATOR_FLAG_GLOBAL | H2O_CONFIGURATOR_FLAG_EXPECT_SCALAR, + on_config_temp_buffer_path); + h2o_configurator_define_command(c, "crash-handler", H2O_CONFIGURATOR_FLAG_GLOBAL | H2O_CONFIGURATOR_FLAG_EXPECT_SCALAR, + on_config_crash_handler); + h2o_configurator_define_command(c, "crash-handler.wait-pipe-close", + H2O_CONFIGURATOR_FLAG_GLOBAL | H2O_CONFIGURATOR_FLAG_EXPECT_SCALAR, + on_config_crash_handler_wait_pipe_close); + } + + h2o_access_log_register_configurator(&conf.globalconf); + h2o_compress_register_configurator(&conf.globalconf); + h2o_expires_register_configurator(&conf.globalconf); + h2o_errordoc_register_configurator(&conf.globalconf); + h2o_fastcgi_register_configurator(&conf.globalconf); + h2o_file_register_configurator(&conf.globalconf); + h2o_throttle_resp_register_configurator(&conf.globalconf); + h2o_headers_register_configurator(&conf.globalconf); + h2o_proxy_register_configurator(&conf.globalconf); + h2o_reproxy_register_configurator(&conf.globalconf); + h2o_redirect_register_configurator(&conf.globalconf); + h2o_status_register_configurator(&conf.globalconf); + h2o_http2_debug_state_register_configurator(&conf.globalconf); +#if H2O_USE_MRUBY + h2o_mruby_register_configurator(&conf.globalconf); +#endif + + h2o_config_register_simple_status_handler(&conf.globalconf, (h2o_iovec_t){H2O_STRLIT("main")}, on_extra_status); +} + +int main(int argc, char **argv) +{ + const char *cmd = argv[0], *opt_config_file = H2O_TO_STR(H2O_CONFIG_PATH); + int error_log_fd = -1; + + conf.num_threads = h2o_numproc(); + conf.tfo_queues = H2O_DEFAULT_LENGTH_TCP_FASTOPEN_QUEUE; + conf.launch_time = time(NULL); + + h2o_hostinfo_max_threads = H2O_DEFAULT_NUM_NAME_RESOLUTION_THREADS; + + h2o_sem_init(&ocsp_updater_semaphore, H2O_DEFAULT_OCSP_UPDATER_MAX_THREADS); + + init_openssl(); + setup_configurators(); + + { /* parse options */ + int ch; + static struct option longopts[] = {{"conf", required_argument, NULL, 'c'}, {"mode", required_argument, NULL, 'm'}, + {"test", no_argument, NULL, 't'}, {"version", no_argument, NULL, 'v'}, + {"help", no_argument, NULL, 'h'}, {NULL}}; + while ((ch = getopt_long(argc, argv, "c:m:tvh", longopts, NULL)) != -1) { + switch (ch) { + case 'c': + opt_config_file = optarg; + break; + case 'm': + if (strcmp(optarg, "worker") == 0) { + conf.run_mode = RUN_MODE_WORKER; + } else if (strcmp(optarg, "master") == 0) { + conf.run_mode = RUN_MODE_MASTER; + } else if (strcmp(optarg, "daemon") == 0) { + conf.run_mode = RUN_MODE_DAEMON; + } else if (strcmp(optarg, "test") == 0) { + conf.run_mode = RUN_MODE_TEST; + } else { + fprintf(stderr, "unknown mode:%s\n", optarg); + } + switch (conf.run_mode) { + case RUN_MODE_MASTER: + case RUN_MODE_DAEMON: + if (getenv("SERVER_STARTER_PORT") != NULL) { + fprintf(stderr, "refusing to start in `%s` mode, environment variable SERVER_STARTER_PORT is already set\n", + optarg); + exit(EX_SOFTWARE); + } + break; + default: + break; + } + break; + case 't': + conf.run_mode = RUN_MODE_TEST; + break; + case 'v': + printf("h2o version " H2O_VERSION "\n"); + printf("OpenSSL: %s\n", SSLeay_version(SSLEAY_VERSION)); +#if H2O_USE_MRUBY + printf( + "mruby: YES\n"); /* TODO determine the way to obtain the version of mruby (that is being linked dynamically) */ +#endif + exit(0); + case 'h': + printf("h2o version " H2O_VERSION "\n" + "\n" + "Usage:\n" + " h2o [options]\n" + "\n" + "Options:\n" + " -c, --conf FILE configuration file (default: %s)\n" + " -m, --mode <mode> specifies one of the following mode\n" + " - worker: invoked process handles incoming connections\n" + " (default)\n" + " - daemon: spawns a master process and exits. `error-log`\n" + " must be configured when using this mode, as all\n" + " the errors are logged to the file instead of\n" + " being emitted to STDERR\n" + " - master: invoked process becomes a master process (using\n" + " the `share/h2o/start_server` command) and spawns\n" + " a worker process for handling incoming\n" + " connections. Users may send SIGHUP to the master\n" + " process to reconfigure or upgrade the server.\n" + " - test: tests the configuration and exits\n" + " -t, --test synonym of `--mode=test`\n" + " -v, --version prints the version number\n" + " -h, --help print this help\n" + "\n" + "Please refer to the documentation under `share/doc/h2o` (or available online at\n" + "http://h2o.examp1e.net/) for how to configure the server.\n" + "\n", + H2O_TO_STR(H2O_CONFIG_PATH)); + exit(0); + break; + case ':': + case '?': + exit(EX_CONFIG); + default: + assert(0); + break; + } + } + argc -= optind; + argv += optind; + } + + /* setup conf.server_starter */ + if ((conf.server_starter.num_fds = h2o_server_starter_get_fds(&conf.server_starter.fds)) == SIZE_MAX) + exit(EX_CONFIG); + if (conf.server_starter.fds != 0) { + size_t i; + for (i = 0; i != conf.server_starter.num_fds; ++i) + set_cloexec(conf.server_starter.fds[i]); + conf.server_starter.bound_fd_map = alloca(conf.server_starter.num_fds); + memset(conf.server_starter.bound_fd_map, 0, conf.server_starter.num_fds); + conf.server_starter.env_var = getenv("SERVER_STARTER_PORT"); + } + unsetenv("SERVER_STARTER_PORT"); + + { /* configure */ + yoml_t *yoml; + resolve_tag_arg_t resolve_tag_arg = {{NULL}}; + yoml_parse_args_t parse_args = { + opt_config_file, /* filename */ + NULL, /* mem_set */ + {resolve_tag, &resolve_tag_arg} /* resolve_tag */ + }; + if ((yoml = load_config(&parse_args, NULL)) == NULL) + exit(EX_CONFIG); + if (h2o_configurator_apply(&conf.globalconf, yoml, conf.run_mode != RUN_MODE_WORKER) != 0) + exit(EX_CONFIG); + + dispose_resolve_tag_arg(&resolve_tag_arg); + yoml_free(yoml, NULL); + } + /* calculate defaults (note: open file cached is purged once every loop) */ + conf.globalconf.filecache.capacity = conf.globalconf.http2.max_concurrent_requests_per_connection * 2; + + /* check if all the fds passed in by server::starter were bound */ + if (conf.server_starter.fds != NULL) { + size_t i; + int all_were_bound = 1; + for (i = 0; i != conf.server_starter.num_fds; ++i) { + if (!conf.server_starter.bound_fd_map[i]) { + fprintf(stderr, "no configuration found for fd:%d passed in by $SERVER_STARTER_PORT\n", conf.server_starter.fds[i]); + all_were_bound = 0; + } + } + if (!all_were_bound) { + fprintf(stderr, "note: $SERVER_STARTER_PORT was \"%s\"\n", conf.server_starter.env_var); + return EX_CONFIG; + } + } + + h2o_srand(); + /* handle run_mode == MASTER|TEST */ + switch (conf.run_mode) { + case RUN_MODE_WORKER: + break; + case RUN_MODE_DAEMON: + if (conf.error_log == NULL) { + fprintf(stderr, "to run in `daemon` mode, `error-log` must be specified in the configuration file\n"); + return EX_CONFIG; + } + return run_using_server_starter(cmd, opt_config_file); + case RUN_MODE_MASTER: + return run_using_server_starter(cmd, opt_config_file); + case RUN_MODE_TEST: + printf("configuration OK\n"); + return 0; + } + + if (getenv("H2O_VIA_MASTER") != NULL) { + /* pid_file and error_log are the directives that are handled by the master process (invoking start_server) */ + conf.pid_file = NULL; + conf.error_log = NULL; + } + + { /* raise RLIMIT_NOFILE */ + struct rlimit limit; + if (getrlimit(RLIMIT_NOFILE, &limit) == 0) { + limit.rlim_cur = limit.rlim_max; + if (setrlimit(RLIMIT_NOFILE, &limit) == 0 +#ifdef __APPLE__ + || (limit.rlim_cur = OPEN_MAX, setrlimit(RLIMIT_NOFILE, &limit)) == 0 +#endif + ) { + fprintf(stderr, "[INFO] raised RLIMIT_NOFILE to %d\n", (int)limit.rlim_cur); + } + } + } + + setup_signal_handlers(); + + /* open the log file to redirect STDIN/STDERR to, before calling setuid */ + if (conf.error_log != NULL) { + if ((error_log_fd = h2o_access_log_open_log(conf.error_log)) == -1) + return EX_CONFIG; + } + setvbuf(stdout, NULL, _IOLBF, 0); + setvbuf(stderr, NULL, _IOLBF, 0); + + /* setuid */ + if (conf.globalconf.user != NULL) { + if (h2o_setuidgid(conf.globalconf.user) != 0) { + fprintf(stderr, "failed to change the running user (are you sure you are running as root?)\n"); + return EX_OSERR; + } + if (neverbleed != NULL && neverbleed_setuidgid(neverbleed, conf.globalconf.user, 1) != 0) { + fprintf(stderr, "failed to change the running user of neverbleed daemon\n"); + return EX_OSERR; + } + } else { + if (getuid() == 0) { + fprintf(stderr, "refusing to run as root (and failed to switch to `nobody`); you can use the `user` directive to set " + "the running user\n"); + return EX_CONFIG; + } + } + + /* pid file must be written after setuid, since we need to remove it */ + if (conf.pid_file != NULL) { + FILE *fp = fopen(conf.pid_file, "wt"); + if (fp == NULL) { + fprintf(stderr, "failed to open pid file:%s:%s\n", conf.pid_file, strerror(errno)); + return EX_OSERR; + } + fprintf(fp, "%d\n", (int)getpid()); + fclose(fp); + } + + { /* initialize SSL_CTXs for session resumption and ticket-based resumption (also starts memcached client threads for the + purpose) */ + size_t i, j; + H2O_VECTOR(SSL_CTX *) ssl_contexts = {NULL}; + for (i = 0; i != conf.num_listeners; ++i) { + for (j = 0; j != conf.listeners[i]->ssl.size; ++j) { + h2o_vector_reserve(NULL, &ssl_contexts, ssl_contexts.size + 1); + ssl_contexts.entries[ssl_contexts.size++] = conf.listeners[i]->ssl.entries[j]->ctx; + } + } + ssl_setup_session_resumption(ssl_contexts.entries, ssl_contexts.size); + free(ssl_contexts.entries); + } + + /* all setup should be complete by now */ + + /* replace STDIN to an closed pipe */ + { + int fds[2]; + if (pipe(fds) != 0) { + perror("pipe failed"); + return EX_OSERR; + } + close(fds[1]); + dup2(fds[0], 0); + close(fds[0]); + } + + /* redirect STDOUT and STDERR to error_log (if specified) */ + if (error_log_fd != -1) { + if (dup2(error_log_fd, 1) == -1 || dup2(error_log_fd, 2) == -1) { + perror("dup(2) failed"); + return EX_OSERR; + } + close(error_log_fd); + error_log_fd = -1; + } + + fprintf(stderr, "h2o server (pid:%d) is ready to serve requests\n", (int)getpid()); + + assert(conf.num_threads != 0); + + /* start the threads */ + conf.threads = alloca(sizeof(conf.threads[0]) * conf.num_threads); + h2o_barrier_init(&conf.startup_sync_barrier, conf.num_threads); + size_t i; + for (i = 1; i != conf.num_threads; ++i) { + pthread_t tid; + h2o_multithread_create_thread(&tid, NULL, run_loop, (void *)i); + } + + /* this thread becomes the first thread */ + run_loop((void *)0); + + /* notreached */ + return 0; +} diff --git a/web/server/h2o/libh2o/src/setuidgid.c b/web/server/h2o/libh2o/src/setuidgid.c new file mode 100644 index 00000000..f663cff1 --- /dev/null +++ b/web/server/h2o/libh2o/src/setuidgid.c @@ -0,0 +1,78 @@ +/* + * Copyright (c) 2015 DeNA Co., Ltd., Kazuho Oku + * + * 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. + */ +#include <errno.h> +#include <grp.h> +#include <pwd.h> +#include <stdio.h> +#include <string.h> +#include <sys/types.h> +#include <unistd.h> + +/* taken from sysexits.h */ +#ifndef EX_OSERR +#define EX_OSERR 71 +#endif +#ifndef EX_CONFIG +#define EX_CONFIG 78 +#endif + +int main(int argc, char **argv) +{ + struct passwd *user; + + if (argc < 3) { + fprintf(stderr, "no command (usage: setuidgid user cmd args...)\n"); + return EX_CONFIG; + } + --argc; + ++argv; + + errno = 0; + if ((user = getpwnam(*argv)) == NULL) { + if (errno == 0) { + fprintf(stderr, "unknown user:%s\n", *argv); + return EX_CONFIG; + } else { + perror("getpwnam"); + return EX_OSERR; + } + } + --argc; + ++argv; + + if (setgid(user->pw_gid) != 0) { + perror("setgid failed"); + return EX_OSERR; + } + if (initgroups(user->pw_name, user->pw_gid) != 0) { + perror("initgroups failed"); + return EX_OSERR; + } + if (setuid(user->pw_uid) != 0) { + perror("setuid failed"); + return EX_OSERR; + } + + execvp(*argv, argv); + fprintf(stderr, "execvp failed to launch file:%s:%s\n", *argv, strerror(errno)); + return EX_OSERR; +} diff --git a/web/server/h2o/libh2o/src/ssl.c b/web/server/h2o/libh2o/src/ssl.c new file mode 100644 index 00000000..7ac6c4c9 --- /dev/null +++ b/web/server/h2o/libh2o/src/ssl.c @@ -0,0 +1,962 @@ +/* + * Copyright (c) 2015 DeNA Co., Ltd., Kazuho Oku + * + * 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. + */ +#include <assert.h> +#include <inttypes.h> +#include <pthread.h> +#include <sys/stat.h> +#include <openssl/crypto.h> +#include <openssl/err.h> +#include <openssl/evp.h> +#include <openssl/rand.h> +#include <openssl/ssl.h> +#include "yoml-parser.h" +#include "yrmcds.h" +#if H2O_USE_PICOTLS +#include "picotls.h" +#include "picotls/openssl.h" +#endif +#include "h2o/file.h" +#include "h2o.h" +#include "h2o/configurator.h" +#include "standalone.h" + +struct st_session_ticket_generating_updater_conf_t { + const EVP_CIPHER *cipher; + const EVP_MD *md; +}; + +struct st_session_ticket_file_updater_conf_t { + const char *filename; +}; + +static struct { + struct { + void (*setup)(SSL_CTX **contexts, size_t num_contexts); + union { + struct { + size_t num_threads; + char *prefix; + } memcached; + } vars; + } cache; + struct { + void *(*update_thread)(void *conf); + union { + struct st_session_ticket_generating_updater_conf_t generating; + struct { + struct st_session_ticket_generating_updater_conf_t generating; /* at same address as conf.ticket.vars.generating */ + h2o_iovec_t key; + } memcached; + struct st_session_ticket_file_updater_conf_t file; + } vars; + } ticket; + unsigned lifetime; + struct { + char *host; + uint16_t port; + int text_protocol; + } memcached; +} conf; + +H2O_NORETURN static void *cache_cleanup_thread(void *_contexts) +{ + SSL_CTX **contexts = _contexts; + + while (1) { + size_t i; + for (i = 0; contexts[i] != NULL; ++i) + SSL_CTX_flush_sessions(contexts[i], time(NULL)); + sleep(conf.lifetime / 4); + } +} + +static void spawn_cache_cleanup_thread(SSL_CTX **_contexts, size_t num_contexts) +{ + /* copy the list of contexts */ + SSL_CTX **contexts = malloc(sizeof(*contexts) * (num_contexts + 1)); + h2o_memcpy(contexts, _contexts, sizeof(*contexts) * num_contexts); + contexts[num_contexts] = NULL; + + /* launch the thread */ + pthread_t tid; + pthread_attr_t attr; + pthread_attr_init(&attr); + pthread_attr_setdetachstate(&attr, 1); + h2o_multithread_create_thread(&tid, &attr, cache_cleanup_thread, contexts); +} + +static void setup_cache_disable(SSL_CTX **contexts, size_t num_contexts) +{ + size_t i; + for (i = 0; i != num_contexts; ++i) + SSL_CTX_set_session_cache_mode(contexts[i], SSL_SESS_CACHE_OFF); +} + +static void setup_cache_internal(SSL_CTX **contexts, size_t num_contexts) +{ + size_t i; + for (i = 0; i != num_contexts; ++i) { + SSL_CTX_set_session_cache_mode(contexts[i], SSL_SESS_CACHE_SERVER | SSL_SESS_CACHE_NO_AUTO_CLEAR); + SSL_CTX_set_timeout(contexts[i], conf.lifetime); + } + spawn_cache_cleanup_thread(contexts, num_contexts); +} + +static void setup_cache_memcached(SSL_CTX **contexts, size_t num_contexts) +{ + h2o_memcached_context_t *memc_ctx = + h2o_memcached_create_context(conf.memcached.host, conf.memcached.port, conf.memcached.text_protocol, + conf.cache.vars.memcached.num_threads, conf.cache.vars.memcached.prefix); + h2o_accept_setup_async_ssl_resumption(memc_ctx, conf.lifetime); + size_t i; + for (i = 0; i != num_contexts; ++i) { + SSL_CTX_set_session_cache_mode(contexts[i], SSL_SESS_CACHE_SERVER | SSL_SESS_CACHE_NO_AUTO_CLEAR); + SSL_CTX_set_timeout(contexts[i], conf.lifetime); + h2o_socket_ssl_async_resumption_setup_ctx(contexts[i]); + } + spawn_cache_cleanup_thread(contexts, num_contexts); +} + +static void cache_init_defaults(void) +{ + conf.cache.setup = setup_cache_internal; +} + +#if H2O_USE_SESSION_TICKETS + +struct st_session_ticket_t { + unsigned char name[16]; + struct { + const EVP_CIPHER *cipher; + unsigned char *key; + } cipher; + struct { + const EVP_MD *md; + unsigned char *key; + } hmac; + uint64_t not_before; + uint64_t not_after; +}; + +typedef H2O_VECTOR(struct st_session_ticket_t *) session_ticket_vector_t; + +static struct { + pthread_rwlock_t rwlock; + session_ticket_vector_t tickets; /* sorted from newer to older */ +} session_tickets = { +/* we need writer-preferred lock, but on linux PTHREAD_RWLOCK_INITIALIZER is reader-preferred */ +#ifdef PTHREAD_RWLOCK_WRITER_NONRECURSIVE_INITIALIZER_NP + PTHREAD_RWLOCK_WRITER_NONRECURSIVE_INITIALIZER_NP +#else + PTHREAD_RWLOCK_INITIALIZER +#endif + , + {NULL} /* tickets */ +}; + +static struct st_session_ticket_t *new_ticket(const EVP_CIPHER *cipher, const EVP_MD *md, uint64_t not_before, uint64_t not_after, + int fill_in) +{ + int key_len = EVP_CIPHER_key_length(cipher), block_size = EVP_MD_block_size(md); + struct st_session_ticket_t *ticket = h2o_mem_alloc(sizeof(*ticket) + key_len + block_size); + + ticket->cipher.cipher = cipher; + ticket->cipher.key = (unsigned char *)ticket + sizeof(*ticket); + ticket->hmac.md = md; + ticket->hmac.key = ticket->cipher.key + key_len; + ticket->not_before = not_before; + ticket->not_after = not_after; + if (fill_in) { + RAND_bytes(ticket->name, sizeof(ticket->name)); + RAND_bytes(ticket->cipher.key, key_len); + RAND_bytes(ticket->hmac.key, block_size); + } + + return ticket; +} + +static void free_ticket(struct st_session_ticket_t *ticket) +{ + int key_len = EVP_CIPHER_key_length(ticket->cipher.cipher), block_size = EVP_MD_block_size(ticket->hmac.md); + h2o_mem_set_secure(ticket, 0, sizeof(*ticket) + key_len + block_size); + free(ticket); +} + +static int ticket_sort_compare(const void *_x, const void *_y) +{ + struct st_session_ticket_t *x = *(void **)_x, *y = *(void **)_y; + + if (x->not_before != y->not_before) + return x->not_before > y->not_before ? -1 : 1; + return memcmp(x->name, y->name, sizeof(x->name)); +} + +static void free_tickets(session_ticket_vector_t *tickets) +{ + size_t i; + for (i = 0; i != tickets->size; ++i) + free_ticket(tickets->entries[i]); + free(tickets->entries); + memset(tickets, 0, sizeof(*tickets)); +} + +static struct st_session_ticket_t *find_ticket_for_encryption(session_ticket_vector_t *tickets, uint64_t now) +{ + size_t i; + + for (i = 0; i != tickets->size; ++i) { + struct st_session_ticket_t *ticket = tickets->entries[i]; + if (ticket->not_before <= now) { + if (now <= ticket->not_after) { + return ticket; + } else { + return NULL; + } + } + } + return NULL; +} + +static int ticket_key_callback(unsigned char *key_name, unsigned char *iv, EVP_CIPHER_CTX *ctx, HMAC_CTX *hctx, int enc) +{ + int ret; + pthread_rwlock_rdlock(&session_tickets.rwlock); + + if (enc) { + RAND_bytes(iv, EVP_MAX_IV_LENGTH); + struct st_session_ticket_t *ticket = find_ticket_for_encryption(&session_tickets.tickets, time(NULL)), *temp_ticket = NULL; + if (ticket != NULL) { + } else { + /* create a dummy ticket and use (this is the only way to continue the handshake; contrary to the man pages, OpenSSL + * crashes if we return zero */ + ticket = temp_ticket = new_ticket(EVP_aes_256_cbc(), EVP_sha256(), 0, UINT64_MAX, 1); + } + memcpy(key_name, ticket->name, sizeof(ticket->name)); + EVP_EncryptInit_ex(ctx, ticket->cipher.cipher, NULL, ticket->cipher.key, iv); + HMAC_Init_ex(hctx, ticket->hmac.key, EVP_MD_block_size(ticket->hmac.md), ticket->hmac.md, NULL); + if (temp_ticket != NULL) + free_ticket(ticket); + ret = 1; + } else { + struct st_session_ticket_t *ticket; + size_t i; + for (i = 0; i != session_tickets.tickets.size; ++i) { + ticket = session_tickets.tickets.entries[i]; + if (memcmp(ticket->name, key_name, sizeof(ticket->name)) == 0) + goto Found; + } + /* not found */ + ret = 0; + goto Exit; + Found: + EVP_DecryptInit_ex(ctx, ticket->cipher.cipher, NULL, ticket->cipher.key, iv); + HMAC_Init_ex(hctx, ticket->hmac.key, EVP_MD_block_size(ticket->hmac.md), ticket->hmac.md, NULL); + /* Request renewal if the youngest key is active */ + if (i != 0 && session_tickets.tickets.entries[i - 1]->not_before <= time(NULL)) + ret = 2; + else + ret = 1; + } + +Exit: + pthread_rwlock_unlock(&session_tickets.rwlock); + return ret; +} + +static int ticket_key_callback_ossl(SSL *ssl, unsigned char *key_name, unsigned char *iv, EVP_CIPHER_CTX *ctx, HMAC_CTX *hctx, + int enc) +{ + return ticket_key_callback(key_name, iv, ctx, hctx, enc); +} + +#if H2O_USE_PICOTLS + +static int encrypt_ticket_key_ptls(ptls_encrypt_ticket_t *self, ptls_t *tls, int is_encrypt, ptls_buffer_t *dst, ptls_iovec_t src) +{ + return (is_encrypt ? ptls_openssl_encrypt_ticket : ptls_openssl_decrypt_ticket)(dst, src, ticket_key_callback); +} + +#endif + +static int update_tickets(session_ticket_vector_t *tickets, uint64_t now) +{ + int altered = 0, has_valid_ticket; + + /* remove old entries */ + while (tickets->size != 0) { + struct st_session_ticket_t *oldest = tickets->entries[tickets->size - 1]; + if (now <= oldest->not_after) + break; + tickets->entries[--tickets->size] = NULL; + free_ticket(oldest); + altered = 1; + } + + /* create new entry if necessary */ + has_valid_ticket = find_ticket_for_encryption(tickets, now) != NULL; + if (!has_valid_ticket || (tickets->entries[0]->not_before + conf.lifetime / 4 < now)) { + uint64_t not_before = has_valid_ticket ? now + 60 : now; + struct st_session_ticket_t *ticket = new_ticket(conf.ticket.vars.generating.cipher, conf.ticket.vars.generating.md, + not_before, not_before + conf.lifetime - 1, 1); + h2o_vector_reserve(NULL, tickets, tickets->size + 1); + memmove(tickets->entries + 1, tickets->entries, sizeof(tickets->entries[0]) * tickets->size); + ++tickets->size; + tickets->entries[0] = ticket; + altered = 1; + } + + return altered; +} + +H2O_NORETURN static void *ticket_internal_updater(void *unused) +{ + while (1) { + pthread_rwlock_wrlock(&session_tickets.rwlock); + update_tickets(&session_tickets.tickets, time(NULL)); + pthread_rwlock_unlock(&session_tickets.rwlock); + /* sleep for certain amount of time */ + sleep(120 - (h2o_rand() >> 16) % 7); + } +} + +static int serialize_ticket_entry(char *buf, size_t bufsz, struct st_session_ticket_t *ticket) +{ + char *name_buf = alloca(sizeof(ticket->name) * 2 + 1); + h2o_hex_encode(name_buf, ticket->name, sizeof(ticket->name)); + int key_len = EVP_CIPHER_key_length(ticket->cipher.cipher), block_size = EVP_MD_block_size(ticket->hmac.md); + char *key_buf = alloca((key_len + block_size) * 2 + 1); + h2o_hex_encode(key_buf, ticket->cipher.key, key_len); + h2o_hex_encode(key_buf + key_len * 2, ticket->hmac.key, block_size); + + return snprintf(buf, bufsz, "- name: %s\n" + " cipher: %s\n" + " hash: %s\n" + " key: %s\n" + " not_before: %" PRIu64 "\n" + " not_after: %" PRIu64 "\n", + name_buf, OBJ_nid2sn(EVP_CIPHER_type(ticket->cipher.cipher)), OBJ_nid2sn(EVP_MD_type(ticket->hmac.md)), key_buf, + ticket->not_before, ticket->not_after); +} + +static struct st_session_ticket_t *parse_ticket_entry(yoml_t *element, char *errstr) +{ + yoml_t *t; + struct st_session_ticket_t *ticket; + unsigned char name[sizeof(ticket->name) + 1], *key; + const EVP_CIPHER *cipher; + const EVP_MD *hash; + uint64_t not_before, not_after; + + errstr[0] = '\0'; + + if (element->type != YOML_TYPE_MAPPING) { + strcpy(errstr, "node is not a mapping"); + return NULL; + } + +#define FETCH(n, post) \ + do { \ + if ((t = yoml_get(element, n)) == NULL) { \ + strcpy(errstr, " mandatory attribute `" n "` is missing"); \ + return NULL; \ + } \ + if (t->type != YOML_TYPE_SCALAR) { \ + strcpy(errstr, "attribute `" n "` is not a string"); \ + return NULL; \ + } \ + post \ + } while (0) + + FETCH("name", { + if (strlen(t->data.scalar) != sizeof(ticket->name) * 2) { + strcpy(errstr, "length of `name` attribute is not 32 bytes"); + return NULL; + } + if (h2o_hex_decode(name, t->data.scalar, sizeof(ticket->name) * 2) != 0) { + strcpy(errstr, "failed to decode the hex-encoded name"); + return NULL; + } + }); + FETCH("cipher", { + if ((cipher = EVP_get_cipherbyname(t->data.scalar)) == NULL) { + strcpy(errstr, "cannot find the named cipher algorithm"); + return NULL; + } + }); + FETCH("hash", { + if ((hash = EVP_get_digestbyname(t->data.scalar)) == NULL) { + strcpy(errstr, "cannot find the named hash algorgithm"); + return NULL; + } + }); + FETCH("key", { + size_t keylen = EVP_CIPHER_key_length(cipher) + EVP_MD_block_size(hash); + if (strlen(t->data.scalar) != keylen * 2) { + sprintf(errstr, "length of the `key` attribute is incorrect (is %zu, must be %zu)\n", strlen(t->data.scalar), + keylen * 2); + return NULL; + } + key = alloca(keylen + 1); + if (h2o_hex_decode(key, t->data.scalar, keylen * 2) != 0) { + strcpy(errstr, "failed to decode the hex-encoded key"); + return NULL; + } + }); + FETCH("not_before", { + if (sscanf(t->data.scalar, "%" SCNu64, ¬_before) != 1) { + strcpy(errstr, "failed to parse the `not_before` attribute"); + return NULL; + } + }); + FETCH("not_after", { + if (sscanf(t->data.scalar, "%" SCNu64, ¬_after) != 1) { + strcpy(errstr, "failed to parse the `not_after` attribute"); + return NULL; + } + }); + if (!(not_before <= not_after)) { + strcpy(errstr, "`not_after` is not equal to or greater than `not_before`"); + return NULL; + } + +#undef FETCH + + ticket = new_ticket(cipher, hash, not_before, not_after, 0); + memcpy(ticket->name, name, sizeof(ticket->name)); + memcpy(ticket->cipher.key, key, EVP_CIPHER_key_length(cipher)); + memcpy(ticket->hmac.key, key + EVP_CIPHER_key_length(cipher), EVP_MD_block_size(hash)); + return ticket; +} + +static int parse_tickets(session_ticket_vector_t *tickets, const void *src, size_t len, char *errstr) +{ + yaml_parser_t parser; + yoml_t *doc; + size_t i; + + *tickets = (session_ticket_vector_t){NULL}; + yaml_parser_initialize(&parser); + + yaml_parser_set_input_string(&parser, src, len); + yoml_parse_args_t parse_args = {NULL, h2o_mem_set_secure}; + if ((doc = yoml_parse_document(&parser, NULL, &parse_args)) == NULL) { + sprintf(errstr, "parse error at line %d:%s\n", (int)parser.problem_mark.line, parser.problem); + goto Error; + } + if (doc->type != YOML_TYPE_SEQUENCE) { + strcpy(errstr, "root element is not a sequence"); + goto Error; + } + for (i = 0; i != doc->data.sequence.size; ++i) { + char errbuf[256]; + struct st_session_ticket_t *ticket = parse_ticket_entry(doc->data.sequence.elements[i], errbuf); + if (ticket == NULL) { + sprintf(errstr, "at element index %zu:%s\n", i, errbuf); + goto Error; + } + h2o_vector_reserve(NULL, tickets, tickets->size + 1); + tickets->entries[tickets->size++] = ticket; + } + + yoml_free(doc, h2o_mem_set_secure); + yaml_parser_delete(&parser); + return 0; +Error: + if (doc != NULL) + yoml_free(doc, h2o_mem_set_secure); + yaml_parser_delete(&parser); + free_tickets(tickets); + return -1; +} + +static h2o_iovec_t serialize_tickets(session_ticket_vector_t *tickets) +{ + h2o_iovec_t data = {h2o_mem_alloc(tickets->size * 1024 + 1), 0}; + size_t i; + + for (i = 0; i != tickets->size; ++i) { + struct st_session_ticket_t *ticket = tickets->entries[i]; + size_t l = serialize_ticket_entry(data.base + data.len, 1024, ticket); + if (l > 1024) { + fprintf(stderr, "[src/ssl.c] %s:internal buffer overflow\n", __func__); + goto Error; + } + data.len += l; + } + + return data; +Error: + free(data.base); + return (h2o_iovec_t){NULL}; +} + +static int ticket_memcached_update_tickets(yrmcds *conn, h2o_iovec_t key, time_t now) +{ + yrmcds_response resp; + yrmcds_error err; + uint32_t serial; + session_ticket_vector_t tickets = {NULL}; + h2o_iovec_t tickets_serialized = {NULL}; + int retry = 0; + char errbuf[256]; + + /* retrieve tickets on memcached */ + if ((err = yrmcds_get(conn, key.base, key.len, 0, &serial)) != 0) { + fprintf(stderr, "[lib/ssl.c] %s:yrmcds_get failed:%s\n", __func__, yrmcds_strerror(err)); + goto Exit; + } + if ((err = yrmcds_recv(conn, &resp)) != 0) { + fprintf(stderr, "[lib/ssl.c] %s:yrmcds_recv failed:%s\n", __func__, yrmcds_strerror(err)); + goto Exit; + } + if (resp.serial != serial) { + fprintf(stderr, "[lib/ssl.c] %s:unexpected response\n", __func__); + goto Exit; + } + if (resp.status == YRMCDS_STATUS_OK) { + int r = parse_tickets(&tickets, resp.data, resp.data_len, errbuf); + h2o_mem_set_secure((void *)resp.data, 0, resp.data_len); + if (r != 0) { + fprintf(stderr, "[lib/ssl.c] %s:failed to parse response:%s\n", __func__, errbuf); + goto Exit; + } + } + if (tickets.size > 1) + qsort(tickets.entries, tickets.size, sizeof(tickets.entries[0]), ticket_sort_compare); + + /* if we need to update the tickets, atomically update the value in memcached, and request refetch to the caller */ + if (update_tickets(&tickets, now) != 0) { + tickets_serialized = serialize_tickets(&tickets); + if (resp.status == YRMCDS_STATUS_NOTFOUND) { + if ((err = yrmcds_add(conn, key.base, key.len, tickets_serialized.base, tickets_serialized.len, 0, conf.lifetime, 0, 0, + &serial)) != 0) { + fprintf(stderr, "[lib/ssl.c] %s:yrmcds_add failed:%s\n", __func__, yrmcds_strerror(err)); + goto Exit; + } + } else { + if ((err = yrmcds_set(conn, key.base, key.len, tickets_serialized.base, tickets_serialized.len, 0, conf.lifetime, + resp.cas_unique, 0, &serial)) != 0) { + fprintf(stderr, "[lib/ssl.c] %s:yrmcds_set failed:%s\n", __func__, yrmcds_strerror(err)); + goto Exit; + } + } + if ((err = yrmcds_recv(conn, &resp)) != 0) { + fprintf(stderr, "[lib/ssl.c] %s:yrmcds_recv failed:%s\n", __func__, yrmcds_strerror(err)); + goto Exit; + } + retry = 1; + goto Exit; + } + + /* store the results */ + pthread_rwlock_wrlock(&session_tickets.rwlock); + h2o_mem_swap(&session_tickets.tickets, &tickets, sizeof(tickets)); + pthread_rwlock_unlock(&session_tickets.rwlock); + +Exit: + free(tickets_serialized.base); + free_tickets(&tickets); + return retry; +} + +H2O_NORETURN static void *ticket_memcached_updater(void *unused) +{ + while (1) { + /* connect */ + yrmcds conn; + yrmcds_error err; + size_t failcnt; + for (failcnt = 0; (err = yrmcds_connect(&conn, conf.memcached.host, conf.memcached.port)) != YRMCDS_OK; ++failcnt) { + if (failcnt == 0) + fprintf(stderr, "[src/ssl.c] failed to connect to memcached at %s:%" PRIu16 ", %s\n", conf.memcached.host, + conf.memcached.port, yrmcds_strerror(err)); + sleep(10); + } + if (conf.memcached.text_protocol) + yrmcds_text_mode(&conn); + /* connected */ + while (ticket_memcached_update_tickets(&conn, conf.ticket.vars.memcached.key, time(NULL))) + ; + /* disconnect */ + yrmcds_close(&conn); + sleep(60); + } +} + +static int load_tickets_file(const char *fn) +{ +#define ERR_PREFIX "failed to load session ticket secrets from file:%s:" + + h2o_iovec_t data = {NULL}; + session_ticket_vector_t tickets = {NULL}; + char errbuf[256]; + int ret = -1; + + /* load yaml */ + data = h2o_file_read(fn); + if (data.base == NULL) { + char errbuf[256]; + strerror_r(errno, errbuf, sizeof(errbuf)); + fprintf(stderr, ERR_PREFIX "%s\n", fn, errbuf); + goto Exit; + } + /* parse the data */ + if (parse_tickets(&tickets, data.base, data.len, errbuf) != 0) { + fprintf(stderr, ERR_PREFIX "%s\n", fn, errbuf); + goto Exit; + } + /* sort the ticket entries being read */ + if (tickets.size > 1) + qsort(tickets.entries, tickets.size, sizeof(tickets.entries[0]), ticket_sort_compare); + /* replace the ticket list */ + pthread_rwlock_wrlock(&session_tickets.rwlock); + h2o_mem_swap(&session_tickets.tickets, &tickets, sizeof(tickets)); + pthread_rwlock_unlock(&session_tickets.rwlock); + + ret = 0; +Exit: + free(data.base); + free_tickets(&tickets); + return ret; + +#undef ERR_PREFIX +} + +H2O_NORETURN static void *ticket_file_updater(void *unused) +{ + time_t last_mtime = 1; /* file is loaded if mtime changes, 0 is used to indicate that the file was missing */ + + while (1) { + struct stat st; + if (stat(conf.ticket.vars.file.filename, &st) != 0) { + if (last_mtime != 0) { + char errbuf[256]; + strerror_r(errno, errbuf, sizeof(errbuf)); + fprintf(stderr, "cannot load session ticket secrets from file:%s:%s\n", conf.ticket.vars.file.filename, errbuf); + } + last_mtime = 0; + } else if (last_mtime != st.st_mtime) { + /* (re)load */ + last_mtime = st.st_mtime; + if (load_tickets_file(conf.ticket.vars.file.filename) == 0) + fprintf(stderr, "session ticket secrets have been (re)loaded\n"); + } + sleep(10); + } +} + +static void ticket_init_defaults(void) +{ + conf.ticket.update_thread = ticket_internal_updater; + /* to protect the secret >>>2030 we need AES-256 (http://www.keylength.com/en/4/) */ + conf.ticket.vars.generating.cipher = EVP_aes_256_cbc(); + /* integrity checks are only necessary at the time of handshake, and sha256 (recommended by RFC 5077) is sufficient */ + conf.ticket.vars.generating.md = EVP_sha256(); +} + +#endif + +int ssl_session_resumption_on_config(h2o_configurator_command_t *cmd, h2o_configurator_context_t *ctx, yoml_t *node) +{ + enum { + MODE_CACHE = 1, + MODE_TICKET = 2, + }; + int modes = -1, uses_memcached; + yoml_t *t; + + if ((t = yoml_get(node, "mode")) == NULL) { + h2o_configurator_errprintf(cmd, node, "mandatory attribute `mode` is missing"); + return -1; + } + if (t->type == YOML_TYPE_SCALAR) { + if (strcasecmp(t->data.scalar, "off") == 0) { + modes = 0; + } else if (strcasecmp(t->data.scalar, "all") == 0) { + modes = MODE_CACHE; +#if H2O_USE_SESSION_TICKETS + modes |= MODE_TICKET; +#endif + } else if (strcasecmp(t->data.scalar, "cache") == 0) { + modes = MODE_CACHE; + } else if (strcasecmp(t->data.scalar, "ticket") == 0) { + modes = MODE_TICKET; + } + } + if (modes == -1) { + h2o_configurator_errprintf(cmd, t, "value of `mode` must be one of: off | all | cache | ticket"); + return -1; + } + + if ((modes & MODE_CACHE) != 0) { + cache_init_defaults(); + if ((t = yoml_get(node, "cache-store")) != NULL) { + if (t->type == YOML_TYPE_SCALAR) { + if (strcasecmp(t->data.scalar, "internal") == 0) { + /* preserve the default */ + t = NULL; + } else if (strcasecmp(t->data.scalar, "memcached") == 0) { + conf.cache.setup = setup_cache_memcached; + t = NULL; + } + } + if (t != NULL) { + h2o_configurator_errprintf(cmd, t, "value of `cache-store` must be one of: internal | memcached"); + return -1; + } + } + if (conf.cache.setup == setup_cache_memcached) { + conf.cache.vars.memcached.num_threads = 1; + conf.cache.vars.memcached.prefix = "h2o:ssl-session-cache:"; + if ((t = yoml_get(node, "cache-memcached-num-threads")) != NULL) { + if (!(t->type == YOML_TYPE_SCALAR && sscanf(t->data.scalar, "%zu", &conf.cache.vars.memcached.num_threads) == 1 && + conf.cache.vars.memcached.num_threads != 0)) { + h2o_configurator_errprintf(cmd, t, "`cache-memcached-num-threads` must be a positive number"); + return -1; + } + } + if ((t = yoml_get(node, "cache-memcached-prefix")) != NULL) { + if (t->type != YOML_TYPE_SCALAR) { + h2o_configurator_errprintf(cmd, t, "`cache-memcached-prefix` must be a string"); + return -1; + } + conf.cache.vars.memcached.prefix = h2o_strdup(NULL, t->data.scalar, SIZE_MAX).base; + } + } + } else { + conf.cache.setup = setup_cache_disable; + } + + if ((modes & MODE_TICKET) != 0) { +#if H2O_USE_SESSION_TICKETS + ticket_init_defaults(); + if ((t = yoml_get(node, "ticket-store")) != NULL) { + if (t->type == YOML_TYPE_SCALAR) { + if (strcasecmp(t->data.scalar, "internal") == 0) { + /* ok, preserve the defaults */ + t = NULL; + } else if (strcasecmp(t->data.scalar, "file") == 0) { + conf.ticket.update_thread = ticket_file_updater; + t = NULL; + } else if (strcasecmp(t->data.scalar, "memcached") == 0) { + conf.ticket.update_thread = ticket_memcached_updater; + t = NULL; + } + } + if (t != NULL) { + h2o_configurator_errprintf(cmd, t, "value of `ticket-store` must be one of: internal | file"); + return -1; + } + } + if (conf.ticket.update_thread == ticket_internal_updater || conf.ticket.update_thread == ticket_memcached_updater) { + /* generating updater takes two arguments: cipher, hash */ + if ((t = yoml_get(node, "ticket-cipher")) != NULL) { + if (t->type != YOML_TYPE_SCALAR || + (conf.ticket.vars.generating.cipher = EVP_get_cipherbyname(t->data.scalar)) == NULL) { + h2o_configurator_errprintf(cmd, t, "unknown cipher algorithm"); + return -1; + } + } + if ((t = yoml_get(node, "ticket-hash")) != NULL) { + if (t->type != YOML_TYPE_SCALAR || + (conf.ticket.vars.generating.md = EVP_get_digestbyname(t->data.scalar)) == NULL) { + h2o_configurator_errprintf(cmd, t, "unknown hash algorithm"); + return -1; + } + } + if (conf.ticket.update_thread == ticket_memcached_updater) { + conf.ticket.vars.memcached.key = h2o_iovec_init(H2O_STRLIT("h2o:ssl-session-key")); + if ((t = yoml_get(node, "ticket-memcached-prefix")) != NULL) { + if (t->type != YOML_TYPE_SCALAR) { + h2o_configurator_errprintf(cmd, t, "`ticket-memcached-key` must be a string"); + return -1; + } + conf.ticket.vars.memcached.key = h2o_strdup(NULL, t->data.scalar, SIZE_MAX); + } + } + } else if (conf.ticket.update_thread == ticket_file_updater) { + /* file updater reads the contents of the file and uses it as the session ticket secret */ + if ((t = yoml_get(node, "ticket-file")) == NULL) { + h2o_configurator_errprintf(cmd, node, "mandatory attribute `file` is missing"); + return -1; + } + if (t->type != YOML_TYPE_SCALAR) { + h2o_configurator_errprintf(cmd, node, "`file` must be a string"); + return -1; + } + conf.ticket.vars.file.filename = h2o_strdup(NULL, t->data.scalar, SIZE_MAX).base; + } +#else + h2o_configurator_errprintf( + cmd, mode, "ticket-based session resumption cannot be used, the server is built without support for the feature"); + return -1; +#endif + } else { + conf.ticket.update_thread = NULL; + } + + if ((t = yoml_get(node, "memcached")) != NULL) { + conf.memcached.host = NULL; + conf.memcached.port = 11211; + conf.memcached.text_protocol = 0; + size_t index; + for (index = 0; index != t->data.mapping.size; ++index) { + yoml_t *key = t->data.mapping.elements[index].key; + yoml_t *value = t->data.mapping.elements[index].value; + if (value == t) + continue; + if (key->type != YOML_TYPE_SCALAR) { + h2o_configurator_errprintf(cmd, key, "attribute must be a string"); + return -1; + } + if (strcmp(key->data.scalar, "host") == 0) { + if (value->type != YOML_TYPE_SCALAR) { + h2o_configurator_errprintf(cmd, value, "`host` must be a string"); + return -1; + } + conf.memcached.host = h2o_strdup(NULL, value->data.scalar, SIZE_MAX).base; + } else if (strcmp(key->data.scalar, "port") == 0) { + if (!(value->type == YOML_TYPE_SCALAR && sscanf(value->data.scalar, "%" SCNu16, &conf.memcached.port) == 1)) { + h2o_configurator_errprintf(cmd, value, "`port` must be a number"); + return -1; + } + } else if (strcmp(key->data.scalar, "protocol") == 0) { + ssize_t sel = h2o_configurator_get_one_of(cmd, value, "BINARY,ASCII"); + if (sel == -1) + return -1; + conf.memcached.text_protocol = (int)sel; + } else { + h2o_configurator_errprintf(cmd, key, "unknown attribute: %s", key->data.scalar); + return -1; + } + } + if (conf.memcached.host == NULL) { + h2o_configurator_errprintf(cmd, t, "mandatory attribute `host` is missing"); + return -1; + } + } + + uses_memcached = conf.cache.setup == setup_cache_memcached; +#if H2O_USE_SESSION_TICKETS + uses_memcached = (uses_memcached || conf.ticket.update_thread == ticket_memcached_updater); +#endif + if (uses_memcached && conf.memcached.host == NULL) { + h2o_configurator_errprintf(cmd, node, "configuration of memcached is missing"); + return -1; + } + + if ((t = yoml_get(node, "lifetime")) != NULL) { + if (!(t->type == YOML_TYPE_SCALAR && sscanf(t->data.scalar, "%u", &conf.lifetime) == 1 && conf.lifetime != 0)) { + h2o_configurator_errprintf(cmd, t, "value of `lifetime` must be a positive number"); + return -1; + } + } + + return 0; +} + +void ssl_setup_session_resumption(SSL_CTX **contexts, size_t num_contexts) +{ + if (conf.cache.setup != NULL) + conf.cache.setup(contexts, num_contexts); + +#if H2O_USE_SESSION_TICKETS + if (num_contexts == 0) + return; + + if (conf.ticket.update_thread != NULL) { + /* start session ticket updater thread */ + pthread_t tid; + pthread_attr_t attr; + pthread_attr_init(&attr); + pthread_attr_setdetachstate(&attr, 1); + h2o_multithread_create_thread(&tid, &attr, conf.ticket.update_thread, NULL); + size_t i; + for (i = 0; i != num_contexts; ++i) { + SSL_CTX *ctx = contexts[i]; + SSL_CTX_set_tlsext_ticket_key_cb(ctx, ticket_key_callback_ossl); +#if H2O_USE_PICOTLS + ptls_context_t *pctx = h2o_socket_ssl_get_picotls_context(ctx); + if (pctx != NULL) { + static ptls_encrypt_ticket_t encryptor = {encrypt_ticket_key_ptls}; + pctx->ticket_lifetime = 86400 * 7; // FIXME conf.lifetime; + pctx->encrypt_ticket = &encryptor; + } +#endif + } + } else { + size_t i; + for (i = 0; i != num_contexts; ++i) + SSL_CTX_set_options(contexts[i], SSL_CTX_get_options(contexts[i]) | SSL_OP_NO_TICKET); + } +#endif +} + +static pthread_mutex_t *mutexes; + +static void lock_callback(int mode, int n, const char *file, int line) +{ + if ((mode & CRYPTO_LOCK) != 0) { + pthread_mutex_lock(mutexes + n); + } else if ((mode & CRYPTO_UNLOCK) != 0) { + pthread_mutex_unlock(mutexes + n); + } else { + assert(!"unexpected mode"); + } +} + +static unsigned long thread_id_callback(void) +{ + return (unsigned long)pthread_self(); +} + +static int add_lock_callback(int *num, int amount, int type, const char *file, int line) +{ + (void)type; + (void)file; + (void)line; + + return __sync_add_and_fetch(num, amount); +} + +void init_openssl(void) +{ + int nlocks = CRYPTO_num_locks(), i; + mutexes = h2o_mem_alloc(sizeof(*mutexes) * nlocks); + for (i = 0; i != nlocks; ++i) + pthread_mutex_init(mutexes + i, NULL); + CRYPTO_set_locking_callback(lock_callback); + CRYPTO_set_id_callback(thread_id_callback); + CRYPTO_set_add_lock_callback(add_lock_callback); + + /* Dynamic locks are only used by the CHIL engine at this time */ + + SSL_load_error_strings(); + SSL_library_init(); + OpenSSL_add_all_algorithms(); + + cache_init_defaults(); +#if H2O_USE_SESSION_TICKETS + ticket_init_defaults(); +#endif + conf.lifetime = 3600; /* default value for session timeout is 1 hour */ +} diff --git a/web/server/h2o/libh2o/src/standalone.h b/web/server/h2o/libh2o/src/standalone.h new file mode 100644 index 00000000..567031f4 --- /dev/null +++ b/web/server/h2o/libh2o/src/standalone.h @@ -0,0 +1,37 @@ +/* + * Copyright (c) 2014,2015 DeNA Co., Ltd., Kazuho Oku + * + * 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. + */ +#ifndef h2o__standalone_h +#define h2o__standalone_h + +#include <openssl/ssl.h> + +#if defined(SSL_CTRL_SET_TLSEXT_TICKET_KEY_CB) && !defined(OPENSSL_NO_TLSEXT) +#define H2O_USE_SESSION_TICKETS 1 +#else +#define H2O_USE_SESSION_TICKETS 0 +#endif + +void init_openssl(void); +void ssl_setup_session_resumption(SSL_CTX **contexts, size_t num_contexts); +int ssl_session_resumption_on_config(h2o_configurator_command_t *cmd, h2o_configurator_context_t *ctx, yoml_t *node); + +#endif diff --git a/web/server/h2o/libh2o/srcdoc/benchmarks.mt b/web/server/h2o/libh2o/srcdoc/benchmarks.mt new file mode 100644 index 00000000..a0096cc4 --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/benchmarks.mt @@ -0,0 +1,48 @@ +? my $note = $main::context->{note}; +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Benchmarks")->(sub { + +<h3 id="download-timings">Download Timings</h3> + +<div> +<p> +Providing quick response to user is more important than anything else in web performance tuning. +According to a research conducted by Microsoft, 500msec slowdown in Bing causes their revenue go down by 1.2%<?= $note->(q{<a href="http://radar.oreilly.com/2009/07/velocity-making-your-site-fast.html">Velocity and the Bottom Line - O'Reilly Radar</a>}) ?>. +</p> +<p> +The chart below compares the first-paint times and download completion times of different web browsers / HTTP servers on a simulated network of 8Mbps bandwidth with 100ms latency, which is typical for today's mobile networks<?= $note->(q{<a href="https://github.com/kazuho/http2rulez.com">A fork of http2rulez.com</a> was used as the target website; bandwidth and latency were induced to local network using <a href="http://linux-ip.net/articles/Traffic-Control-HOWTO/components.html">qdisc</a>, specifically by running <code>tc qdisc replace dev eth1 root handle 1:0 tbf rate 8192kbit burst 2048 latency 100ms; sudo tc qdisc add dev eth1 parent 1:1 netem delay 100ms</code>, and <code>sysctl -w net.ipv4.tcp_no_metrics_save=1</code>.}) ?>. +</p> +<div align="center"> +<a href="assets/8mbps100msec-nginx195-h2o150.png" target="_blank"><img src="assets/8mbps100msec-nginx195-h2o150.png" height="300"></a> +</div> +<p> +It is clear in the case of this benchmark that the visitors of the web site would be more satisfied, if H2O was used as the HTTP server. +</p> +</div> + +<h3 id="static-file">Static-File Serving</h3> + +<div> +<p> +Below chart shows the scores recorded on Amazon EC2 running two c3.8xlarge instances (server and client) on a single network placement, serving a 612-byte file<?= $note->(q{Configuration files used: <a href="https://gist.github.com/kazuho/def1e71281ed4ae07b95">nginx.conf</a>, <a href="https://gist.github.com/kazuho/969bb99bae31d67e01c4">h2o.conf</a>.}) ?>. +For each measurement, 250 concurrent clients were used<?= $note->(q{<a href="https://github.com/wg/wrk">Wrk</a> was used for HTTP/1 tests. <a href="https://nghttp2.org/documentation/h2load-howto.html">h2load</a> was used for HTTP/2.}) ?>. +<code>open_file_cache</code> was used for Nginx. +H2O implements a open-file-cache that gets updated immediately when the files are replaced. +</p> +<div align="center"> +<a href="assets/staticfile612-nginx1910-h2o170.png" target="_blank"><img src="assets/staticfile612-nginx1910-h2o170.png" height="300"></a> +</div> +</div> + +<h3 id="reverse-proxy">Reverse Proxy</h3> + +<div> +<p> +Presented below is an old chart showing the scores recorded on Amazon EC2 running two c3.8xlarge instances (server and client) on a single network placement<?= $note->("For reverse-proxy tests, another H2O process running on the same host was used as the upstream server") ?><?= $note->("open-file-cache was not used in the static-file benchmark") ?>. +</p> +<div align="center"> +<a href="assets/remotebench.png" target="_blank"><img src="assets/remotebench.png" width="400"></a> +</div> +</div> + +? }) diff --git a/web/server/h2o/libh2o/srcdoc/configure.mt b/web/server/h2o/libh2o/srcdoc/configure.mt new file mode 100644 index 00000000..5c8799f8 --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/configure.mt @@ -0,0 +1,43 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Configure")->(sub { + +<ul style="list-style: none; font-weight: bold;"> +<li><a href="configure/quick_start.html">Quick Start</a> +<li><a href="configure/command_options.html">Command Options</a> +<li>Configuration File +<ul> +<li><a href="configure/syntax_and_structure.html">Syntax and Structure</a> +</ul> +<li>Configuration Directives +<ul> +<li><a href="configure/base_directives.html">Base</a> +<li><a href="configure/http1_directives.html">HTTP/1</a> +<li><a href="configure/http2_directives.html">HTTP/2</a> +<li><a href="configure/access_log_directives.html">Access Log</a> +<li><a href="configure/compress_directives.html">Compress</a> +<li><a href="configure/errordoc_directives.html">Errordoc</a> +<li><a href="configure/expires_directives.html">Expires</a> +<li><a href="configure/fastcgi_directives.html">FastCGI</a> +<li><a href="configure/file_directives.html">File</a> +<li><a href="configure/headers_directives.html">Headers</a> +<li><a href="configure/mruby_directives.html">Mruby</a> +<li><a href="configure/proxy_directives.html">Proxy</a> +<li><a href="configure/redirect_directives.html">Redirect</a> +<li><a href="configure/reproxy_directives.html">Reproxy</a> +<li><a href="configure/status_directives.html">Status</a> +<li><a href="configure/throttle_response_directives.html">Throttle Response</a> +</ul> +</li> +<li>How-To +<ul> +<li><a href="configure/basic_auth.html">Using Basic Authentication</a></li> +<li><a href="configure/cgi.html">Using CGI</a></li> +<li><a href="configure/mruby.html">Using Mruby</a></li> +<li><a href="configure/dos_detection.html">Using DoS Detection</a></li> +<li><a href="configure/access_control.html">Access Control</a></li> +</ul> +</li> +<li><a href="https://github.com/h2o/h2o/wiki#configuration-examples" target="_blank">Configuration Examples (Wiki)</a> +</ul> + +? }) diff --git a/web/server/h2o/libh2o/srcdoc/configure/access_control.mt b/web/server/h2o/libh2o/srcdoc/configure/access_control.mt new file mode 100644 index 00000000..4a613ac6 --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/configure/access_control.mt @@ -0,0 +1,273 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Configure", "Access Control")->(sub { + +<p> +Starting from version 2.1, H2O comes with a DSL-like mruby library which makes it easy to write access control list (ACL). +</p> + +<h2 id="example" class="section-head">Example</h2> + +<p> +Below example uses this Access Control feature to write various access control. +</p> + +<?= $ctx->{example}->('Access Control', <<'EOT'); +paths: + "/": + mruby.handler: | + acl { + allow { addr == "127.0.0.1" } + deny { user_agent.match(/curl/i) && ! addr.start_with?("192.168.") } + respond(503, {}, ["Service Unavailable"]) { addr == malicious_ip } + redirect("https://example.com/", 301) { path =~ /moved/ } + use Htpasswd.new("/path/to/.htpasswd", "realm") { path.start_with?("/admin") } + } + file.dir: /path/to/doc_root +EOT +?> + +<p> +In the example, the handler you get by calling <code>acl</code> method will do the following: +<ul> + <li> + if the remote IP address is exactly equal to "127.0.0.1", the request will be delegated to the next handler (i.e. serve files under /path/to/doc_root) and all following acl settings are ignored + </li> + <li> + otherwise, if the user agent string includes "curl" and the remote IP address doesn't start with "192.168.", this handler immediately returns <code>403 Forbidden</code> response + </li> + <li> + otherwise, if the remote IP address is exactly equal to the <code>malicious_ip</code> variable, this handler immediately returns <code>503 Service Unavailable</code> response + </li> + <li> + otherwise, if the request path matches with the pattern <code>/moved/i</code>, this handler immediately redirects the client to <code>"https://example.com"</code> with <code>301</code> status code + </li> + <li> + otherwise, if the request path starts with <code>/admin</code>, apply Basic Authentication to the request (for details of Basic Authentication, see <a href="configure/basic_auth.html">here</a>). + </li> + <li> + otherwise, the request will be delegated to the next handler (i.e. serve files under /path/to/doc_root) + </li> + +</ul> + +<h2 id="acl-methods" class="section-head">ACL Methods</h2> + +<p> +An ACL handler is built by calling ACL methods, which can be used like directives. +ACL methods can only be used in <code>acl</code> block. +</p> + +<p> +Each ACL method adds a filter to the handler, which checks whether the request matches the provided condition or not. +Every ACL method can be accompanied by a condition block, which should return boolean value. +</p> + +<p> +The filter defined by the method that first matched the accompanying condition gets applied (e.g. response <code>403 Forbidden</code>, redirect to somewhere). +If a condition block is omitted, all requests matches. +If none of the conditions matches the request, the handler returns <code>399</code> and the request will be delegated to the next handler. +</p> + +<? +$ctx->{mruby_method}->( + name => "allow", + desc => q{ Adds a filter which delegates the request to the next handler if the request matches the provided condition. }, +)->(sub { +?> +<pre><code>allow { ..condition.. }</code></pre> +? }) + +<? +$ctx->{mruby_method}->( + name => "deny", + desc => q{ Adds a filter which returns <code>403 Forbidden</code> if the request matches the provided condition. }, +)->(sub { +?> +<pre><code>deny { ..condition.. }</code></pre> +? }) + +<? +$ctx->{mruby_method}->( + name => "redirect", + params => [ + { label => 'location', desc => 'Location to which the client will be redirected. Required.' }, + { label => 'status', desc => 'Status code of the response. Default value: 302' }, + ], + desc => q{ Adds a filter which redirects the client if the request matches the provided condition. }, +)->(sub { +?> +<pre><code>redirect(location, status) { ..condition.. }</code></pre> +? }) + +<? +$ctx->{mruby_method}->( + name => "respond", + params => [ + { label => 'status', desc => 'Status code of the response. Required.' }, + { label => 'header', desc => 'Header key-value pairs of the response. Default value: {}' }, + { label => 'body', desc => 'Body array of the response. Default value: []' }, + ], + desc => q{ Adds a filter which returns arbitrary response if the request matches the provided condition. }, +)->(sub { +?> +<pre><code>respond(status, header, body) { ..condition.. }</code></pre> +? }) + +<? +$ctx->{mruby_method}->( + name => "use", + params => [ + { label => 'proc', desc => 'Callable object that should be applied' }, + ], + desc => q{ Adds a filter which applies the provided handler (callable object) if the request matches the provided condition. }, +)->(sub { +?> +<pre><code>use(proc) { ..condition.. }</code></pre> +? }) + +<h2 id="matching-methods" class="section-head">Matching Methods</h2> + +<p> +In a condition block, you can use helpful methods which return particular properties of the request as string values. +Matching methods can only be used in a condition block of the ACL methods. +</p> + +<? +$ctx->{mruby_method}->( + name => "addr", + params => [ + { label => 'forwarded', desc => 'If true, returns the value of X-Forwarded-For header if it exists. Default value: true' }, + ], + desc => q{ Returns the remote IP address of the request. }, +)->(sub { +?> +<pre><code>addr(forwarded)</code></pre> +? }) + +<? +$ctx->{mruby_method}->( + name => "path", + desc => q{ Returns the requested path string of the request. }, +)->(sub { +?> +<pre><code>path()</code></pre> +? }) + +<? +$ctx->{mruby_method}->( + name => "method", + desc => q{ Returns the HTTP method of the request. }, +)->(sub { +?> +<pre><code>method()</code></pre> +? }) + +<? +$ctx->{mruby_method}->( + name => "header", + params => [ + { label => 'name', desc => 'Case-insensitive header name. Required.' }, + ], + desc => q{ Returns the header value of the request associated with the provided name. }, +)->(sub { +?> +<pre><code>header(name)</code></pre> +? }) + +<? +$ctx->{mruby_method}->( + name => "user_agent", + desc => q{ Shortcut for header("user-agent"). }, +)->(sub { +?> +<pre><code>user_agent()</code></pre> +? }) + +<h2 id="caution" class="section-head">Caution</h2> + +<p> +Several restrictions are introduced to avoid misconfiguration when using <code>acl</code> method. +<ul> +<li><code>acl</code> method can be called only once in each handler configuration</li> +<li>If <code>acl</code> method is used, the handler returned by the configuration directive must be the one returned by the <code>acl</code> method</li> +</ul> +If a configuration violates these restrictions, the server will detect it and refuse to launch with error message. +</p> + +<p> +For example, both of the following examples violate the restrictions above, so the server will refuse to start up. +</p> + +<?= $ctx->{example}->('Misconfiguration Example 1', <<'EOT'); +paths: + "/": + mruby.handler: | + acl { # this block will be ignored! + allow { addr == "127.0.0.1" } + } + acl { + deny + } + file.dir: /path/to/doc_root +EOT +?> + +<?= $ctx->{example}->('Misconfiguration Example 2', <<'EOT'); +paths: + "/": + mruby.handler: | + acl { # this block will be ignored! + allow { addr == "127.0.0.1" } + deny + } + proc {|env| [399, {}, []} + file.dir: /path/to/doc_root +EOT +?> + +<p> +You can correct these like the following: +</p> + +<?= $ctx->{example}->('Valid Configuration Example', <<'EOT'); +paths: + "/": + mruby.handler: | + acl { + allow { addr == "127.0.0.1" } + deny + } + file.dir: /path/to/doc_root +EOT +?> + +<h2 id="how-to" class="section-head">How-To</h2> + +<h3 id="matching-ip-address-blocks">Matching IP Address Blocks</h3> + +<p> +You can match an IP address against predefined list of address blocks using a script named <a href="">trie_addr.rb</a>. +</p> +<p> +Below is an example. +</p> + +<?= $ctx->{example}->('Address Block Matching Example', <<'EOT'); +paths: + "/": + mruby.handler: | + require "trie_addr.rb" + trie = TrieAddr.new.add(["192.168.0.0/16", "172.16.0.0/12"]) + acl { + allow { trie.match?(addr) } + deny + } + file.dir: /path/to/doc_root +EOT +?> + +<p> +This library currently supports only IPv4 addresses. <code>TrieAddr#match?</code> returns <code>false</code> when it receives an invalid IPv4 address (including an IPv6 address) as an argument.. +</p> + +? }) diff --git a/web/server/h2o/libh2o/srcdoc/configure/access_log_directives.mt b/web/server/h2o/libh2o/srcdoc/configure/access_log_directives.mt new file mode 100644 index 00000000..52a585ba --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/configure/access_log_directives.mt @@ -0,0 +1,134 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Configure", "Access Log Directives")->(sub { + +<p> +This document describes the configuration directives of the access_log handler. +</p> + +<? +$ctx->{directive}->( + name => "access-log", + levels => [ qw(global host path extension) ], + see_also => render_mt(<<'EOT'), +<a href="configure/base_directives.html#error-log"><code>error-log</code></a> +<a href="configure/base_directives.html#error-log.emit-request-errors"><code>error-log.emit-request-errors</code></a> +EOT + desc => q{The directive sets the path and optionally the format of the access log.}, +)->(sub { +?> +<p> +If the supplied argument is a scalar, it is treated as the path of the log file, or if the value starts with a <code>|</code>, it is treated as a command to which the log should be emitted. +</p> +<?= $ctx->{example}->('Emit access log to file', <<'EOT') +access-log: /path/to/access-log-file +EOT +?> +<?= $ctx->{example}->('Emit access log through pipe', <<'EOT') +access-log: "| rotatelogs /path/to/access-log-file.%Y%m%d 86400" +EOT +?> + +<p> +If the supplied argument is a mapping, its <code>path</code> property is considered as the path of the log file or the pipe command, and the <code>format</code> property is treated as the format of the log file. +Starting from version 2.2, <code>escape</code> property can be used to specify the escape sequence that should be used to emit unsafe octets. +</p> + +<p> +Two forms of escape sequences are supported. +If <code>apache</code> is specified as the value of the <code>escape</code> property, unsafe octets are emitted in the form of <code>\xNN</code>, where N is a hexadecimal number in lower case. +If <code>json</code> is specified, unsafe octets are emitted in the form of <code>\u00NN</code>. +<code>apache</code> is the default escape method. +</p> + +<?= $ctx->{example}->('Emit access log to file using Common Log Format', <<'EOT') +access-log: + path: /path/to/access-log-file + format: "%h %l %u %t \"%r\" %s %b" + escape: apache +EOT +?> + +<p> +The list of format strings recognized by H2O is as follows. +</p> + +<table> +<tr><th>Format String<th>Description +<tr><td><code>%%</code><td>the percent sign +<tr><td><code>%A</code><td>local address (e.g. <code>4.5.6.7</code>) +<tr><td><code>%b</code><td>size of the response body in bytes +<tr><td><code>%H</code><td>request protocol as sent by the client (e.g. <code>HTTP/1.1</code>) +<tr><td><code>%h</code><td>remote address (e.g. <code>1.2.3.4</code>) +<tr><td><code>%l</code><td>remote logname (always <code>-</code>) +<tr><td><code>%m</code><td>request method (e.g. <code>GET</code>, <code>POST</code>) +<tr><td><code>%p</code><td>local port (<code>%{local}p</code> is a synonym that is supported since version 2.2) +<tr><td><code>%{remote}p</code><td>remote port (since version 2.2) +<tr><td><code>%q</code><td>query string (<code>?</code> is prepended if exists, otherwise an empty string) +<tr><td><code>%r</code><td>request line (e.g. <code>GET / HTTP/1.1</code>) +<tr><td><code>%s</code><td>status code sent to client (e.g. <code>200</code>) +<tr><td><code>%<s</code><td>status code received from upstream (or initially generated) +<tr><td><code>%t</code><td>time when the request was received in format: <code>[02/Jan/2006:15:04:05 -0700]</code> +<tr><td><code>%{<i>FORMAT</i>}t</code><td>time when the request was received using the specified format. <code>FORMAT</code> should be an argument to <code>strftime</code>, or one of: +<table> +<tr><td><code>sec</code><td>number of seconds since Epoch +<tr><td><code>msec</code><td>number of milliseconds since Epoch +<tr><td><code>usec</code><td>number of microseconds since Epoch +<tr><td><code>msec_frac</code><td>millisecond fraction +<tr><td><code>usec_frac</code><td>microsecond fraction +</table> +As an example, it is possible to log timestamps in millisecond resolution using <code>%{%Y/%m/%d:%H:%M:%S}t.%{msec_frac}t</code>, which results in a timestamp like <code>2006-01-02:15:04:05.000</code>. +<tr><td><code>%U</code><td>requested URL path, not including the query string +<tr><td><code>%u</code><td>remote user if the request was authenticated (always <code>-</code>) +<tr><td><code>%V</code><td>requested server name (or the default server name if not specified by the client) +<tr><td><code>%v</code><td>canonical server name +<tr><td><code>%{<i>VARNAME</i>}e</code><td>request environment variable (since version 2.3; see <a href="configure/mruby.html#logging-arbitrary-variable">Logging Arbitrary Variable</a>) +<tr><td><code>%{<i>HEADERNAME</i>}i</code><td>value of the given request header (e.g. <code>%{user-agent}i</code>) +<tr><td><code>%{<i>HEADERNAME</i>}o</code><td>value of the given response header sent to client (e.g. <code>%{set-cookie}o</code>) +<tr><td><code>%<{<i>HEADERNAME</i>}o</code><td>value of the response header received from upstream (or initially generated) +<tr><td><code>%{<i>NAME</i>}x</code><td>various extensions. <code>NAME</code> must be one listed in the following tables. A dash (<code>-</code>) is emitted if the directive is not applicable to the request being logged. +<table> +<caption>Access Timings</caption> +<tr><th>Name<th>Description +<tr><td><code>connect-time</code><td>time spent to establish the connection (i.e. since connection gets <code>accept(2)</code>-ed until first octet of the request is received) +<tr><td><code>request-header-time</code><td>time spent receiving request headers +<tr><td><code>request-body-time</code><td>time spent receiving request body +<tr><td><code>request-total-time</code><td>sum of <code>request-header-time</code> and <code>request-body-time</code> +<tr><td><code>process-time</code><td>time spent after receiving request, before starting to send response +<tr><td><code>response-time</code><td>time spent sending response +<tr><td><code>duration</code><td>sum of <code>request-total-time</code>, <code>process-time</code>, <code>response-time</code> +</table> +<table> +<caption>Connection (since v2.0)</caption> +<tr><th>Name<th>Description +<tr><td><code>connection-id</code><td>64-bit internal ID assigned to every client connection +<tr><td><code>ssl.protocol-version</code><td>SSL protocol version obtained from <a href="https://www.openssl.org/docs/manmaster/ssl/SSL_get_version.html"><code>SSL_get_version</code></a> +<tr><td><code>ssl.session-reused</code><td><code>1</code> if the <a href="configure/base_directives.html#ssl-session-resumption">SSL session was reused</a>, or <code>0</code> if not<?= $ctx->{note}->(q{A single SSL connection may transfer more than one HTTP request.}) ?> +<tr><td><code>ssl.session-id</code><td>base64-encoded value of the session id used for resuming the session (since v2.2) +<tr><td><code>ssl.cipher</code><td>name of the <a href="https://tools.ietf.org/html/rfc5246#appendix-A.5">cipher suite</a> being used, obtained from <a href="https://www.openssl.org/docs/manmaster/ssl/SSL_CIPHER_get_name.html">SSL_CIPHER_get_name</a> +<tr><td><code>ssl.cipher-bits</code><td>strength of the cipher suite in bits +</table> +<table> +<caption>HTTP/2 (since v2.0)</caption> +<tr><th>Name<th>Description +<tr><td><code>http2.stream-id</code><td>stream ID +<tr><td><code>http2.priority.received</code><td>colon-concatenated values of <i>exclusive</i>, <i>parent</i>, <i>weight</i> +<tr><td><code>http2.priority.received.exclusive</code><td>exclusive bit of the most recent priority specified by the client +<tr><td><code>http2.priority.received.parent</code><td>parent stream ID of the most recent priority specified by the client +<tr><td><code>http2.priority.received.weight</code><td>weight of the most recent priority specified by the client +</table> +<table> +<caption>Miscellaneous</caption> +<tr><th>Name<th>Description +<tr><td><code>error</code><td>request-level errors. Unless specified otherwise by using the <a href="configure/base_directives.html#error-log.emit-request-errors"><code>error-log.emit-request-errors</code></a> directive, the same messages are emitted to the <a href="configure/base_directives.html#error-log">error-log</a>. (since v2.1) +</table> +</table> + +<p> +The default format is <code>%h %l %u %t "%r" %s %b "%{Referer}i" "%{User-agent}i"</code>, a.k.a. the <a href="http://httpd.apache.org/docs/2.4/mod/mod_log_config.html.en#examples" target="_blank">NCSA extended/combined log format</a>. +</p> +<p> +Note that you may need to quote (and escape) the format string as required by YAML (see <a href="http://www.yaml.org/YAML_for_ruby.html#single-quoted_strings">Yaml Cookbook</a>). +</p> +? }) + +? }) diff --git a/web/server/h2o/libh2o/srcdoc/configure/base_directives.mt b/web/server/h2o/libh2o/srcdoc/configure/base_directives.mt new file mode 100644 index 00000000..1f6ffe3e --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/configure/base_directives.mt @@ -0,0 +1,690 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Configure", "Base Directives")->(sub { + +<p> +This document describes the configuration directives common to all the protocols and handlers. +</p> + +<? +$ctx->{directive}->( + name => "hosts", + levels => [ qw(global) ], + desc => q{Maps <code>host:port</code> to the mappings of per-host configs.}, +)->(sub { +?> +<p> +The directive specifies the mapping between the authorities (the host or <code>host:port</code> section of an URL) and their configurations. +The directive is mandatory, and must at least contain one entry. +</p> +<p> +When <code>port</code> is omitted, the entry will match the requests targetting the default ports (i.e. port 80 for HTTP, port 443 for HTTPS) with given hostname. +Otherwise, the entry will match the requests targetting the specified port. +</p> +<p> +Since version 1.7, a wildcard character <code>*</code> can be used as the first component of the hostname. +If used, they are matched using the rule defined in <a href="https://tools.ietf.org/html/rfc2818#section-3.1" target="_blank">RFC 2818 Section 3.1</a>. +For example, <code>*.example.com</code> will match HTTP requests for both <code>foo.example.com</code> and <code>bar.example.com</code>. +Note that an exact match is preferred over host definitions using wildcard characters. +</p> + + +<?= $ctx->{example}->('A host redirecting all HTTP requests to HTTPS', <<'EOT'); +hosts: + "www.example.com:80": + listen: + port: 80 + paths: + "/": + redirect: https://www.example.com/ + "www.example.com:443": + listen: + port: 443 + ssl: + key-file: /path/to/ssl-key-file + certificate-file: /path/to/ssl-certificate-file + paths: + "/": + file.dir: /path/to/doc-root +EOT +?> +? }) + +<? +$ctx->{directive}->( + name => "paths", + levels => [ qw(host) ], + desc => q{Mapping of paths and their configurations.}, +)->(sub { +?> +</p> +<p> +The mapping is searched using prefix-match. +The entry with the longest path is chosen when more than one matching paths were found. +An <code>404 Not Found</code> error is returned if no matching paths were found. +</p> +<?= $ctx->{example}->('Configuration with two paths', <<'EOT') +hosts: + "www.example.com": + listen: + port: 80 + paths: + "/": + file.dir: /path/to/doc-root + "/assets": + file.dir: /path/to/assets +EOT +?> +<p> +In releases prior to version 2.0, all the path entries are considered as directories. +When H2O receives a request that exactly matches to an entry in paths that does not end with a slash, the server always returns a 301 redirect that appends a slash. +</p> +<p> +Since 2.0, it depends on the handler of the path whether if a 301 redirect that appends a slash is returned. +Server administrators can take advantage of this change to define per-path configurations (see the examples in <a href="configure/file_directives.html#file.file"><code>file.file</code></a> and the <a href="configure/fastcgi_directives.html">FastCGI handler</a>). +<a href="configure/file_directives.html#file.dir"><code>file.dir</code></a> is an exception that continues to perform the redirection; in case of the example above, access to <code>/assets</code> is redirected to <code>/assets/</code>. +</p> +? }) + +<? +$ctx->{directive}->( + name => "listen", + levels => [ qw(global host) ], + desc => q{Specifies the port at which the server should listen to.}, +)->(sub { +?> +</p> +<p> +In addition to specifying the port number, it is also possible to designate the bind address or the SSL configuration. +</p> +<?= $ctx->{example}->('Various ways of using the Listen Directive', <<'EOT') +# accept HTTP on port 80 on default address (both IPv4 and IPv6) +listen: 80 + +# accept HTTP on 127.0.0.1:8080 +listen: + host: 127.0.0.1 + port: 8080 + +# accept HTTPS on port 443 +listen: + port: 443 + ssl: + key-file: /path/to/key-file + certificate-file: /path/to/certificate-file + +# accept HTTPS on port 443 (using PROXY protocol) +listen: + port: 443 + ssl: + key-file: /path/to/key-file + certificate-file: /path/to/certificate-file + proxy-protocol: ON +EOT +?> +<h4 id="listen-configuration-levels">Configuration Levels</h4> +<p> +The directive can be used either at global-level or at host-level. +At least one <code>listen</code> directive must exist at the global level, or every <i>host</i>-level configuration must have at least one <code>listen</code> directive. +</p> +<p> +Incoming connections accepted by global-level listeners will be dispatched to one of the host-level contexts with the corresponding <code>host:port</code>, or to the first host-level context if none of the contexts were given <code>host:port</code> corresponding to the request. +</p> +<p> +Host-level listeners specify bind addresses specific to the host-level context. +However it is permitted to specify the same bind address for more than one host-level contexts, in which case hostname-based lookup will be performed between the host contexts that share the address. +The feature is useful for setting up a HTTPS virtual host using <a href="https://tools.ietf.org/html/rfc6066">Server-Name Indication (RFC 6066)</a>. +</p> +<?= $ctx->{example}->('Using host-level listeners for HTTPS virtual-hosting', <<'EOT') +hosts: + "www.example.com:443": + listen: + port: 443 + ssl: + key-file: /path/to/www_example_com.key + certificate-file: /path/to/www_example_com.crt + paths: + "/": + file.dir: /path/to/doc-root_of_www_example_com + "www.example.jp:443": + listen: + port: 443 + ssl: + key-file: /path/to/www_example_jp.key + certificate-file: /path/to/www_example_jp.crt + paths: + "/": + file.dir: /path/to/doc-root_of_www_example_jp +EOT +?> +<h4 id="listen-ssl">SSL Attribute</h4> +<p> +The <code style="font-weight: bold;">ssl</code> attribute must be defined as a mapping, and recognizes the following attributes. +</p> +<dl> +<dt id="certificate-file">certificate-file:</dt> +<dd>path of the SSL certificate file (mandatory)</dd> +<dt id="key-file">key-file:</dt> +<dd>path of the SSL private key file (mandatory)</dd> +<dt id="minimum-version">minimum-version:</dt> +<dd> +minimum protocol version, should be one of: <code>SSLv2</code>, <code>SSLv3</code>, <code>TLSv1</code>, <code>TLSv1.1</code>, <code>TLSv1.2</code>. +Default is <code>TLSv1</code> +</dd> +<dt id="min-version">min-verison:</dt> +<dd> +synonym of <code>minimum-version</code> (introduced in version 2.2) +</dd> +<dt id="maximum-version">maximum-version:</dt> +<dd> +maximum protocol version. +Introduced in version 2.2. +Default is the maximum protocol version supported by the server. +</dd> +<dt id="maximum-version">max-version:</dt> +<dd> +synonym of <code>maximum-version</code>. +</dd> +<dt id="cipher-suite">cipher-suite:</dt> +<dd>list of cipher suites to be passed to OpenSSL via SSL_CTX_set_cipher_list (optional)</dd> +<dt id="cipher-preferences">cipher-preference:</dt> +<dd> +side of the list that should be used for selecting the cipher-suite; should be either of: <code>client</code>, <code>server</code>. +Default is <code>client</code>. +</dd> +<dt id="dh-file">dh-file:</dt> +<dd> +path of a PEM file containing the Diffie-Hellman parameters to be used. +Use of the file is recommended for servers using Diffie-Hellman key agreement. +(optional) +</dd> +<dt id="ocsp-update-interval">ocsp-update-interval:</dt> +<dd> +interval for updating the OCSP stapling data (in seconds), or set to zero to disable OCSP stapling. +Default is <code>14400</code> (4 hours). +</dd> +<dt id="ocsp-max-failures">ocsp-max-failures:</dt> +<dd> +number of consecutive OCSP query failures before stopping to send OCSP stapling data to the client. +Default is 3. +</dd> +<dt id="neverbleed">neverbleed:</dt> +<dd> +unless set to <code>OFF</code>, H2O isolates RSA private key operations to an isolated process by using <a href="https://github.com/h2o/neverbleed">Neverbleed</a>. +Default is <code>ON</code>. +</dl> +<p> +<a href="configure/base_directives.html#ssl-session-resumption"><code>ssl-session-resumption</code></a> directive is provided for tuning parameters related to session resumption and session tickets. +</p> +<h4 id="listen-proxy-protocol">The Proxy-Protocol Attribute</h4> +<p> +The <code>proxy-protocol</code> attribute (i.e. the value of the attribute must be either <code>ON</code> or <code>OFF</code>) specifies if the server should recognize the information passed via <a href="http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt">"the PROXY protocol</a> in the incoming connections. +The protocol is used by L4 gateways such as <a href="http://aws.amazon.com/jp/elasticloadbalancing/">AWS Elastic Load Balancing</a> to send peer address to the servers behind the gateways. +</p> +<p> +When set to <code>ON</code>, H2O standalone server tries to parse the first octets of the incoming connections as defined in version 1 of the specification, and if successful, passes the addresses obtained from the protocol to the web applications and the logging handlers. +If the first octets do not accord with the specification, it is considered as the start of the SSL handshake or as the beginning of an HTTP request depending on whether if the <code>ssl</code> attribute has been used. +</p> +<p> +Default is <code>OFF</code>. +</p> +<h4 id="listen-unix-socket">Listening to a Unix Socket</h4> +<p> +If the <code>type</code> attribute is set to <code>unix</code>, then the <code>port</code> attribute is assumed to specify the path of the unix socket to which the standalone server should bound. +Also following attributes are recognized. +</p> +<dl> +<dt>owner</dt> +<dd> +username of the owner of the socket file. +If omitted, the socket file will be owned by the launching user. +</dd> +<dt>permission</dt> +<dd> +an octal number specifying the permission of the socket file. +Many operating systems require write permission for connecting to the socket file. +If omitted, the permission of the socket file will reflect the umask of the calling process. +</dd> +</dl> +<?= $ctx->{example}->('Listening to a Unix Socket accessible only by www-data', <<'EOT') +listen: + type: unix + port: /tmp/h2o.sock + owner: www-data + permission: 600 +EOT +?> +? }) + +<? +$ctx->{directive}->( + name => "error-log", + levels => [ qw(global) ], + see_also => render_mt(<<'EOT'), +<a href="configure/base_directives.html#error-log.emit-request-errors"><code>error-log.emit-request-errors</code></a> +EOT + desc => q{Path of the file to which error logs should be appended.}, +)->(sub { +?> +<p> +Default is stderr. +</p> +<p> +If the path starts with <code>|</code>, the rest of the path is considered as a command to which the logs should be piped. +</p> +<?= $ctx->{example}->('Log errors to file', <<'EOT') +error-log: /path/to/error-log-file +EOT +?> +<?= $ctx->{example}->('Log errors through pipe', <<'EOT') +error-log: "| rotatelogs /path/to/error-log-file.%Y%m%d 86400" +EOT +?> +? }) + +<? +$ctx->{directive}->( + name => "error-log.emit-request-errors", + levels => [ qw(global host path extension) ], + since => "2.1", + see_also => render_mt(<<'EOT'), +<a href="configure/access_log_directives.html#access-log"><code>access-log</code></a> +<a href="configure/base_directives.html#error-log"><code>error-log</code></a> +EOT + default => "error-log.emit-request-errors: ON", + desc => q{Sets whether if request-level errors should be emitted to the error log.}, +)->(sub { +?> +By setting the value to <code>OFF</code> and by using the <code>%{error}x</code> specifier of the <a href="configure/access_log_directives.html">access-log</a> directive, it is possible to log request-level errors only to the access log. +? }) + +<? +$ctx->{directive}->( + name => "handshake-timeout", + levels => [ qw(global) ], + default => "handshake-timeout: 10", + desc => q{Maximum time (in seconds) that can be spent by a connection before it becomes ready to accept an HTTP request.}, +)->(sub { +?> +Times spent for receiving <a href="configure/base_directives.html#listen-proxy-protocol">the PROXY protocol</a> and TLS handshake are counted. +? }) + +<? +$ctx->{directive}->( + name => "limit-request-body", + levels => [ qw(global) ], + desc => q{Maximum size of request body in bytes (e.g. content of POST).}, +)->(sub { +?> +<p> +Default is 1073741824 (1GB). +</p> +? }) + +<? +$ctx->{directive}->( + name => "max-connections", + levels => [ qw(global) ], + default => 'max-connections: 1024', + desc => q{Number of connections to handle at once at maximum.}, +)->(sub {}); + +$ctx->{directive}->( + name => "max-delegations", + levels => [ qw(global) ], + default => 'max-delegations: 5', + desc => q{Limits the number of delegations (i.e. internal redirects using the <code>X-Reproxy-URL</code> header).}, +)->(sub {}); + +$ctx->{directive}->( + name => "num-name-resolution-threads", + levels => [ qw(global) ], + default => 'num-name-resolution-threads: 32', + desc => q{Maximum number of threads to run for name resolution.}, +)->(sub {}); +?> + +<? +$ctx->{directive}->( + name => "num-ocsp-updaters", + levels => [ qw(global) ], + since => "2.0", + default => 'num-ocsp-updaters: 10', + desc => q{Maximum number of OCSP updaters.}, +)->(sub { +?> +<p> +<a href="https://en.wikipedia.org/wiki/OCSP_stapling">OSCP Stapling</a> is an optimization that speeds up the time spent for establishing a TLS connection. +In order to <i>staple</i> OCSP information, a HTTP server is required to periodically contact the certificate authority. +This directive caps the number of the processes spawn for collecting the information. +</p> +<p> +The use and the update interval of OCSP can be configured using the <a href="configure/base_directives.html#listen-ssl">SSL attributes</a> of the <a href="configure/base_directives.html#listen"><code>listen</code></a> configuration directive. +</p> +? }); + +<? +$ctx->{directive}->( + name => "num-threads", + levels => [ qw(global) ], + desc => q{Number of worker threads.}, +)->(sub { +?> +<p> +Default is the number of the processors connected to the system as obtained by <code>getconf NPROCESSORS_ONLN</code>. +</p> +? }) + +<? +$ctx->{directive}->( + name => "pid-file", + levels => [ qw(global) ], + desc => q{Name of the file to which the process id of the server should be written.}, +)->(sub { +?> +<p> +Default is none. +</p> +? }) + +<? +$ctx->{directive}->( + name => "tcp-fastopen", + levels => [ qw(global) ], + desc => q{Size of the queue used for TCP Fast Open.}, +)->(sub { +?> +<p> +<a href="https://en.wikipedia.org/wiki/TCP_Fast_Open">TCP Fast Open</a> is an extension to the TCP/IP protocol that reduces the time spent for establishing a connection. +On Linux that support the feature, the default value is <code>4,096</code>. +On other platforms the default value is <code>0</code> (disabled). +</p> +? }) + +<? +$ctx->{directive}->( + name => "send-server-name", + levels => [ qw(global) ], + since => '2.0', + desc => q{A boolean flag (<code>ON</code> or <code>OFF</code>) indicating whether if the <code>server</code> response header should be sent.}, + default => q{send-server-name: ON}, + see_also => render_mt(<<'EOT'), +<a href="configure/base_directives.html#server-name"><code>server-name</code></a> +EOT +)->(sub { +?> +? }) + +<? +$ctx->{directive}->( + name => "server-name", + levels => [ qw(global) ], + since => '2.0', + desc => q{Lets the user override the value of the <code>server</code> response header.}, + see_also => render_mt(<<'EOT'), +<a href="configure/base_directives.html#send-server-name"><code>send-server-name</code></a> +EOT +)->(sub { +?> +The default value is <code>h2o/VERSION-NUMBER</code>. +? }) + +<? +$ctx->{directive}->( + name => "setenv", + levels => [ qw(global host path extension) ], + since => '2.0', + desc => 'Sets one or more environment variables.', + see_also => render_mt(<<'EOT'), +<a href="configure/base_directives.html#unsetenv"><code>unsetenv</code></a> +EOT +)->(sub { +?> +<p> +Environment variables are a set of key-value pairs containing arbitrary strings, that can be read from applications invoked by the standalone server (e.g. <a href="configure/fastcgi_directives.html">fastcgi handler</a>, <a href="configure/mruby_directives.html">mruby handler</a>) and the access logger. +</p> +<p> +The directive is applied from outer-level to inner-level. +At each level, the directive is applied after the <a href="configure/base_directives.html#unsetenv"><code>unsetenv</code></a> directive at the corresponding level is applied. +</p> +<p> +Environment variables are retained through internal redirections. +</p> +<?= $ctx->{example}->('Setting an environment variable named <code>FOO</code>', <<'EOT') +setenv: + FOO: "value_of_FOO" +EOT +?> +? }) + +<? +$ctx->{directive}->( + name => "unsetenv", + levels => [ qw(global host path extension) ], + since => '2.0', + desc => 'Unsets one or more environment variables.', + see_also => render_mt(<<'EOT'), +<a href="configure/base_directives.html#setenv"><code>setenv</code></a> +EOT +)->(sub { +?> +<p> +The directive can be used to have an exception for the paths that have an environment variable set, or can be used to reset variables after an internal redirection. +</p> +<?= $ctx->{example}->('Setting environment variable for <code>example.com</code> excluding <code>/specific-path</code>', <<'EOT') +hosts: + example.com: + setenv: + FOO: "value_of_FOO" + paths: + /specific-path: + unsetenv: + - FOO + ... +EOT +?> +? }) + +<? +$ctx->{directive}->( + name => "ssl-session-resumption", + levels => [ qw(global) ], + desc => q{Configures cache-based and ticket-based session resumption.}, +)->(sub { +?> +<p> +To reduce the latency introduced by the TLS (SSL) handshake, two methods to resume a previous encrypted session are defined by the Internet Engineering Task Force. +H2O supports both of the methods: cache-based session resumption (defined in <a href="https://tools.ietf.org/html/rfc5246">RFC 5246</a>) and ticket-based session resumption (defined in <a href="https://tools.ietf.org/html/rfc5077">RFC 5077</a>). +</p> +<?= $ctx->{example}->('Various session-resumption configurations', <<'EOT'); +# use both methods (storing data on internal memory) +ssl-session-resumption: + mode: all + +# use both methods (storing data on memcached running at 192.168.0.4:11211) +ssl-session-resumption: + mode: all + cache-store: memcached + ticket-store: memcached + cache-memcached-num-threads: 8 + memcached: + host: 192.168.0.4 + port: 11211 + +# use ticket-based resumption only (with secrets used for encrypting the tickets stored in a file) +ssl-session-resumption: + mode: ticket + ticket-store: file + ticket-file: /path/to/ticket-secrets.yaml +EOT +?> +<h4 id="ssl-session-resumption-methods">Defining the Methods Used</h4> +<p> +The <code>mode</code> attribute defines which methods should be used for resuming the TLS sessions. +The value can be either of: <code>off</code>, <code>cache</code>, <code>ticket</code>, <code>all</code>. +Default is <code>all</code>. +</p> +<p> +If set to <code>off</code>, session resumption will be disabled, and all TLS connections will be established via full handshakes. +If set to <code>all</code>, both session-based and ticket-based resumptions will be used, with the preference given to the ticket-based resumption for clients supporting both the methods. +</p> +<p> +For each method, additional attributes can be used to customize their behaviors. +Attributes that modify the behavior of the disabled method are ignored. +</p> +<h4 id="ssl-session-resumption-cache-based">Attributes for Cache-based Resumption</h4> +<p> +Following attributes are recognized if the cache-based session resumption is enabled. +Note that <code>memcached</code> attribute must be defined as well in case the <code>memcached</code> cache-store is used. +</p> +<dl> +<dt>cache-store:</dt> +<dd> +<p> +defines where the cache should be stored, must be one of: <code>internal</code>, <code>memcached</code>. +Default is <code>internal</code>. +</p> +<p> +Please note that if you compiled h2o with OpenSSL 1.1.0 ~ 1.1.0f, session resumption with external cache store would fail due to bug of OpenSSL. +</p> +</dd> +<dt>cache-memcached-num-threads:</dt> +<dd>defines the maximum number of threads used for communicating with the memcached server. +Default is <code>1</code>. +</dd> +<dt>cache-memcached-prefix:</dt> +<dd> +for the <code>memcached</code> store specifies the key prefix used to store the secrets on memcached. +Default is <code>h2o:ssl-session-cache:</code>. +</dd> +</dl> +<h4 id="ssl-session-resumption-ticket-based">Attributes for Ticket-based Resumption</h4> +<p> +Ticket-based session resumption uses master secret(s) to encrypt the keys used for encrypting the data transmitted over TLS connections. +To achieve <a href="https://en.wikipedia.org/wiki/Forward_secrecy" target="_blank">forward-secrecy</a> (i.e. protect past communications from being decrypted in case a master secret gets obtained by a third party), it is essential to periodically change the secret and remove the old ones. +</p> +<p> +Among the three types of stores supported for ticket-based session resumption, the <code>internal</code> store and <code>memcached</code> store implement automatic roll-over of the secrets. +A new master secret is created every 1/4 of the session lifetime (defined by the <code>lifetime</code> attribute), and they expire (and gets removed) after 5/4 of the session lifetime elapse. +</p> +<p> +For the <code>file</code> store, it is the responsibility of the web-site administrator to periodically update the secrets. H2O monitors the file and reloads the secrets when the file is altered. +</p> +<p> +Following attributes are recognized if the ticket-based resumption is enabled. +</p> +<dl> +<dt>ticket-store:</dt> +<dd>defines where the secrets for ticket-based resumption should be / is stored, must be one of: <code>internal</code>, <code>file</code>, <code>memcached</code>. +Default is <code>internal</code>. +<dt>ticket-cipher:</dt> +<dd> +for stores that implement automatic roll-over, specifies the cipher used for encrypting the tickets. +The value must be one recognizable by <code>EVP_get_cipherbyname</code>. +Default is <code>aes-256-cbc</code>. +<dt>ticket-hash:</dt> +<dd> +for stores that implement automatic roll-over, specifies the cipher used for digitally-signing the tickets. +The value must be one recognizable by <code>EVP_get_digestbyname</code>. +Default is <code>sha-256</code>. +</dd> +<dt>ticket-file:</dt> +<dd>for the <code>file</code> store specifies the file in which the secrets are stored</dd> +<dt>ticket-memcached-key:</dt> +<dd> +for the <code>memcached</code> store specifies the key used to store the secrets on memcached. +Default is <code>h2o:ssl-session-ticket</code>. +</dd> +</dl> +<h4 id="ssl-session-resumption-other">Other Attributes</h4> +<p> +Following attributes are common to cache-based and ticket-based session resumption. +</p> +<dl> +<dt>lifetime:</dt> +<dd> +defines the lifetime of a TLS session; when it expires the session cache entry is purged, and establishing a new connection will require a full TLS handshake. +Default value is <code>3600</code> (in seconds). +</dd> +<dt>memcached:</dt> +<dd> +specifies the location of memcached used by the <code>memcached</code> stores. +The value must be a mapping with <code>host</code> attribute specifying the address of the memcached server, and optionally a <code>port</code> attribute specifying the port number (default is <code>11211</code>). +By default, the memcached client uses the <a href="https://github.com/memcached/memcached/blob/master/doc/protocol-binary.xml">BINARY protocol</a>. +Users can opt-in to using the legacy <a href="https://github.com/memcached/memcached/blob/master/doc/protocol.txt">ASCII protocol</a> by adding a <code>protocol</code> attribute set to <code>ASCII</code>. +</dd> +? }) + +<? +$ctx->{directive}->( + name => "temp-buffer-path", + levels => [ qw(global) ], + desc => q{Directory in which temporary buffer files are created.}, + default => q{temp-buffer-path: "/tmp"}, + since => "2.0", + see_also => render_mt(<<'EOT'), +<a href="configure/base_directives.html#user"><code>user</code></a> +EOT +)->(sub { +?> +<p> +H2O uses an internal structure called <code>h2o_buffer_t</code> for buffering various kinds of data (e.g. POST content, response from upstream HTTP or FastCGI server). +When amount of the data allocated in the buffer exceeds 32MB, it starts allocating storage from the directory pointed to by the directive. +</p> +<p> +By using the directive, users can set the directory to one within a memory-backed file system (e.g. <a href="https://en.wikipedia.org/wiki/Tmpfs">tmpfs</a>) for speed, or specify a disk-based file system to avoid memory pressure. +</p> +<p> +Note that the directory must be writable by the running user of the server. +</p> +? }) + +<? +$ctx->{directive}->( + name => "user", + levels => [ qw(global) ], + desc => q{Username under which the server should handle incoming requests.}, +)->(sub { +?> +<p> +If the directive is omitted and if the server is started under root privileges, the server will attempt to <code>setuid</code> to <code>nobody</code>. +</p> +? }) + +<? +$ctx->{directive}->( + name => "crash-handler", + levels => [ qw(global) ], + desc => q{Script to invoke if <code>h2o</code> receives a fatal signal.}, + default => q{crash-handler: "${H2O_ROOT}/share/h2o/annotate-backtrace-symbols"}, + since => "2.1", +)->(sub { +?> +<p>Note: this feature is only available when linking to the GNU libc.</p> + +<p>The script is invoked if one of the <code>SIGABRT</code>, +<code>SIGBUS</code>, <code>SIGFPE</code>, <code>SIGILL</code> or +<code>SIGSEGV</code> signals is received by <code>h2o</code>.</p> + +<p><code>h2o</code> writes the backtrace as provided by +<code>backtrace()</code> and <code>backtrace_symbols_fd</code> to the +standard input of the program.</p> + +<p>If the path is not absolute, it is prefixed with <code>${H2O_ROOT}/</code>.</p> +? }) + +<? +$ctx->{directive}->( + name => "crash-handler.wait-pipe-close", + levels => [ qw(global) ], + desc => q{Whether <code>h2o</code> should wait for the crash handler pipe to close before exiting.}, + default => q{crash-handler.wait-pipe-close: OFF}, + since => "2.1", +)->(sub { +?> +<p>When this setting is <code>ON</code>, <code>h2o</code> will wait +for the pipe to the crash handler to be closed before exiting. +This can be useful if you use a custom handler that inspects the dying +process.</p> +? }) + +? }) diff --git a/web/server/h2o/libh2o/srcdoc/configure/basic_auth.mt b/web/server/h2o/libh2o/srcdoc/configure/basic_auth.mt new file mode 100644 index 00000000..918b4053 --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/configure/basic_auth.mt @@ -0,0 +1,31 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Configure", "Using Basic Authentication")->(sub { + +<p> +Starting from version 1.7, H2O comes with a mruby script named <a href="https://github.com/h2o/h2o/blob/master/share/h2o/mruby/htpasswd.rb">htpasswd.rb</a> that implements <a href="https://tools.ietf.org/html/rfc2617" target="_blank">Basic Authentication</a>. +The script provides a Rack handler that implements Basic Authentication using password files generated by the <a href="https://httpd.apache.org/docs/2.4/programs/htpasswd.html">htpasswd</a> command. +</p> + +<p> +Below example uses the mruby script to restrict access to the path. +If authentication fails, the mruby handler returns a <code>401 Unauthorized</code> response. +If authentication succeeds, the handler returns a <code>399</code> response, and the request is <a href="configure/mruby.html#delegating-request">delegated</a> internally to the next handler (i.e. <code>file.dir</code>). +</p> + +<?= $ctx->{example}->('Configuring HTTP authentication using htpasswd.rb', <<'EOT'); +paths: + "/": + mruby.handler: | + require "htpasswd.rb" + Htpasswd.new("/path/to/.htpasswd", "realm-name") + file.dir: /path/to/doc_root +EOT +?> + +<p> +In H2O versions prior to 2.0, you should specify <code>"#{$H2O_ROOT}/share/h2o/mruby/htpasswd.rb"</code> as the argument to <code>require</code>, since the directory is not registered as part of <code>$LOAD_PATH</code>. +</p> + +For convenience, the mruby script also forbids access to files or directories that start with <code>.ht</code>. + +? }) diff --git a/web/server/h2o/libh2o/srcdoc/configure/cgi.mt b/web/server/h2o/libh2o/srcdoc/configure/cgi.mt new file mode 100644 index 00000000..09da7e93 --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/configure/cgi.mt @@ -0,0 +1,40 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Configure", "Using CGI")->(sub { + +<p> +Starting from version 1.7, H2O comes with a FastCGI-to-CGI gateway (<code>fastcgi-cgi</code>), which can be found under <code>share/h2o</code> directory of the installation path. +The gateway can be used for running CGI scripts through the FastCGI handler. +</p> + +<p> +The example below maps <code>.cgi</code> files to be executed by the gateway. +It is also possible to run CGI scripts under different privileges by specifying the <code>user</code> attribute of the directive. +</p> + +<?= $ctx->{example}->('Execute <code>.cgi</code> files using FastCGI-to-CGI gateway', <<'EOT'); +file.custom-handler: + extension: .cgi + fastcgi.spawn: + command: "exec $H2O_ROOT/share/h2o/fastcgi-cgi" +EOT +?> + +The gateway also provides options to for tuning the behavior. A full list of options can be obtained by running the gateway directly with <code>--help</code> option. + +<?= $ctx->{example}->('Output of <code>share/h2o/fastcgi-cgi --help</code>', <<'EOT'); +$ share/h2o/fastcgi-cgi --help +Usage: + share/h2o/fastcgi-cgi [options] + +Options: + --listen=sockfn path to the UNIX socket. If specified, the program will + create a UNIX socket at given path replacing the existing + file (should it exist). If not, file descriptor zero (0) + will be used as the UNIX socket for accepting new + connections. + --max-workers=nnn maximum number of CGI processes (default: unlimited) + --pass-authz if set, preserves HTTP_AUTHORIZATION parameter +EOT +?> + +? }) diff --git a/web/server/h2o/libh2o/srcdoc/configure/command_options.mt b/web/server/h2o/libh2o/srcdoc/configure/command_options.mt new file mode 100644 index 00000000..b9ea030e --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/configure/command_options.mt @@ -0,0 +1,36 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Configure", "Command Options")->(sub { + +<p> +Full list of command options can be viewed by running <code>h2o --help</code>. +Following is the output of <code>--help</code> as of version 1.2.0. +</p> + +<?= $ctx->{code}->(<< 'EOT') +Options: + -c, --conf FILE configuration file (default: h2o.conf) + -m, --mode <mode> specifies one of the following mode + - worker: invoked process handles incoming connections + (default) + - daemon: spawns a master process and exits. `error-log` + must be configured when using this mode, as all + the errors are logged to the file instead of + being emitted to STDERR + - master: invoked process becomes a master process (using + the `share/h2o/start_server` command) and spawns + a worker process for handling incoming + connections. Users may send SIGHUP to the master + process to reconfigure or upgrade the server. + - test: tests the configuration and exits + -t, --test synonym of `--mode=test` + -v, --version prints the version number + -h, --help print this help +EOT +?> + +<p> +The default path of the configuration file may differ depending on the distribution. +Please run <code>h2o --help</code> to find out the location. +</p> + +? }) diff --git a/web/server/h2o/libh2o/srcdoc/configure/compress_directives.mt b/web/server/h2o/libh2o/srcdoc/configure/compress_directives.mt new file mode 100644 index 00000000..57f7a43e --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/configure/compress_directives.mt @@ -0,0 +1,82 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Configure", "Compress Directives")->(sub { + +<p> +The compress handler performs on-the-fly compression - it compresses the contents of an HTTP response as it is being sent, if the client indicates itself to be capable of decompressing the response transparently with the use of <a href="https://tools.ietf.org/html/rfc7231#section-5.3.4"><code>Accept-Encoding</code></a> header</li>, and if the response is deemed compressible according to the following rules. +</p> +<p> +If <code>x-compress-hint</code> response header does not exist or the value is <code>auto</code>, then whether if the response is considered compressible depends on the <code>is_compressible</code> attribute assigned to the content type (see <a href="configure/file_directives.html#file.mime.addtypes"><code>file.mime.addtypes</code></a>). +If <code>x-compress-hint</code> response header exists and the value is <code>on</code>, the response is always considered to be compressible. +If the value of the response header is set to <code>off</code>, then the response never gets compressed. +</p> + +<p> +The following are the configuration directives recognized by the handler. +</p> + +<? +$ctx->{directive}->( + name => "compress", + levels => [ qw(global host path extension) ], + default => "compress: OFF", + see_also => render_mt(<<'EOT'), +<a href="configure/file_directives.html#file.send-compressed"><code>file.send-compressed</code></a>, <a href="configure/file_directives.html#file.mime.addtypes"><code>file.mime.addtypes</code></a> +EOT + since => '2.0', + desc => <<'EOT', +Enables on-the-fly compression of HTTP response. +EOT +)->(sub { +?> +<p> +If the argument is <code>ON</code>, both <a href="https://datatracker.ietf.org/doc/draft-alakuijala-brotli/">brotli</a> and <a href="https://tools.ietf.org/html/rfc1952">gzip</a> compression are enabled. +If the argument is <code>OFF</code>, on-the-fly compression is disabled. +If the argument is a sequence, the elements are the list of compression algorithms to be enabled. +If the argument is a mapping, each key specifies the compression algorithm to be enabled, and the values specify the quality of the algorithms. +</p> +<p> +When both brotli and gzip are enabled and if the client supports both, H2O is hard-coded to prefer brotli. +</p> +<?= $ctx->{example}->('Enabling on-the-fly compression', <<'EOT') +# enable all algorithms +compress: ON + +# enable by name +compress: [ gzip, br ] + +# enable gzip only +compress: [ gzip ] +EOT +?> +? }) + +<? +$ctx->{directive}->( + name => "compress-minimum-size", + levels => [ qw(global host path extension) ], + default => "compress-minimum-size: 100", + since => '2.0', + desc => <<'EOT', +Defines the minimum size a files needs to have in order for H2O to compress the request. +EOT +)->(sub {}); +?> + +<? +$ctx->{directive}->( + name => "gzip", + levels => [ qw(global host path extension) ], + default => "gzip: OFF", + see_also => render_mt(<<'EOT'), +<a href="configure/compress_directives.html#compress"><code>compress</code></a> +EOT + since => '1.5', + desc => <<'EOT', +Enables on-the-fly compression of HTTP response using gzip. +EOT +)->(sub { +?> +Equivalent to <code>compress: [ gzip ]</code>. +? }) + +? }) diff --git a/web/server/h2o/libh2o/srcdoc/configure/dos_detection.mt b/web/server/h2o/libh2o/srcdoc/configure/dos_detection.mt new file mode 100644 index 00000000..9cba1bf7 --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/configure/dos_detection.mt @@ -0,0 +1,101 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Configure", "Using DoS Detection")->(sub { + +<p> +Starting from version 2.1, H2O comes with a mruby script named <a href="https://github.com/h2o/h2o/blob/master/share/h2o/mruby/dos_detector.rb">dos_detector.rb</a> that implements DoS Detection feature. +The script provides a Rack handler that detects HTTP flooding attacks based on the client's IP address. +</p> + +<h3 id="basic-usage">Basic Usage</h3> + +<p> +Below example uses the mruby script to detect DoS attacks. +The default detecting strategy is simply counting requests within configured period. +If the count exceeds configured threshold, the handler returns a <code>403 Forbidden</code> response. +Otherwise, the handler returns a <code>399</code> response, and the request is <a href="configure/mruby.html#delegating-request">delegated</a> internally to the next handler. +</p> + +<?= $ctx->{example}->('Configuring DoS Detection', <<'EOT'); +paths: + "/": + mruby.handler: | + require "dos_detector.rb" + DoSDetector.new({ + :strategy => DoSDetector::CountingStrategy.new({ + :period => 10, # default + :threshold => 100, # default + :ban_period => 300, # default + }), + }) + file.dir: /path/to/doc_root +EOT +?> + +<p> +In the example above, the handler countup the requests within 10 seconds for each IP address, and when the count exceeds 100, +it returns a <code>403 Forbidden</code> response for the request and marks the client as "Banned" for 300 seconds. While marked as "Banned", the handler returns a <code>403 Forbidden</code> to all requests from the same IP address. +</p> + +<h3 id="configuring-details">Configuring Details</h3> + +<p> +You can pass the following parameters to <code>DoSDetector.new</code> . +<ul> +<li><code>:strategy</code> + <p>The algorithm to detect DoS attacks. You can write and pass your own strategies if needed. The default strategy is <code>DoSDetector.CountingStrategy</code> which takes the following parameters:</p> + <ul> + <li><code>:period</code> + <p>Time window in seconds to count requests. The default value is 10.</p> + </li> + <li><code>:threshold</code> + <p>Threshold count of request. The default value is 100.</p> + </li> + <li><code>:ban_period</code> + <p>Duration in seconds in which "Banned" client continues to be restricted. The default value is 300.</p> + </li> + </ul> +</li> +<li><code>:callback</code> + <p>The callback which is called by the handler with detecting result. You can define your own callback to return arbitrary response, set response headers, etc. The default callback returns <code>403 Forbidden</code> if DoS detected, otherwise delegate the request to the next handler.</p> +</li> +<li><code>:forwarded</code> + <p> + If set true, the handler uses X-HTTP-Forwarded-For header to get client's IP address if the header exists. The default value is true. + </p> +</li> +<li><code>:cache_size</code> + <p> + The capacity of the LRU cache which preserves client's IP address and associated request count. The default value is 128. + </p> +</li> +</ul> +<?= $ctx->{example}->('Configuring Details', <<'EOT'); +paths: + "/": + mruby.handler: | + require "dos_detector.rb" + DoSDetector.new({ + :strategy => DoSDetector::CountingStrategy.new, + :forwarded => false, + :cache_size => 2048, + :callback => proc {|env, detected, ip| + if detected && ! ip.start_with?("192.168.") + [503, {}, ["Service Unavailable"]] + else + [399, {}, []] + end + } + }) + file.dir: /path/to/doc_root +EOT +?> +</p> + +<h3 id="points-to-notice">Points to Notice</h3> +<ul> +<li> + For now, counting requests is "per-thread" and not shared between multiple threads. +</li> +</ul> + +? }) diff --git a/web/server/h2o/libh2o/srcdoc/configure/errordoc_directives.mt b/web/server/h2o/libh2o/srcdoc/configure/errordoc_directives.mt new file mode 100644 index 00000000..94137ae6 --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/configure/errordoc_directives.mt @@ -0,0 +1,52 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Configure", "Errordoc Directives")->(sub { + +<p> +This document describes the configuration directives of the errordoc handler. +</p> + +<? +$ctx->{directive}->( + name => "error-doc", + levels => [ qw(global host path extension) ], + desc => <<'EOT', +Specifies the content to be sent when returning an error response (i.e. a response with 4xx or 5xx status code). +EOT +)->(sub { +?> +<p> +The argument must be a mapping containing following attributes, or if it is a sequence, every element must be a mapping with the following attributes. +<ul> +<li><code>status</code> - three-digit number indicating the status code (or sequence of that from version 2.3) +<li><code>url</code> - URL of the document to be served +</ul> +</p> +<p> +URL can either be absolute or relative. +Only <code>content-type</code>, <code>content-language</code>, <code>set-cookie</code> headers obtained from the specified URL are served to the client. +</p> +<p> +<?= $ctx->{example}->('Set error document for 404 status', <<'EOT') +error-doc: + status: 404 + url: /404.html +EOT +?> +<?= $ctx->{example}->('Set error document for 500 and 503 status', <<'EOT') +error-doc: + - status: 500 + url: /internal-error.html + - status: 503 + url: /service-unavailable.html +EOT +?> +<?= $ctx->{example}->('Set error document for 50x statuses (From version 2.3)', <<'EOT') +error-doc: + status: [500, 502, 503, 504] + url: /50x.html +EOT +?> +</p> +? }) + +? }) diff --git a/web/server/h2o/libh2o/srcdoc/configure/expires_directives.mt b/web/server/h2o/libh2o/srcdoc/configure/expires_directives.mt new file mode 100644 index 00000000..a3b22f85 --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/configure/expires_directives.mt @@ -0,0 +1,32 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Configure", "Expires Directives")->(sub { + +<p> +This document describes the configuration directives of the expires handler. +</p> + +<? +$ctx->{directive}->( + name => "expires", + levels => [ qw(global host path extension) ], + desc => <<'EOT', +An optional directive for setting the <code>Cache-Control: max-age=</code> header. +EOT +)->(sub { +?> +<ul> +<li>if the argument is <code>OFF</code> the feature is not used +<li>if the value is <code><i>NUMBER</i> <i>UNIT</i></code> then the header is set +<li>the units recognized are: <code>second</code>, <code>minute</code>, <code>hour</code>, <code>day</code>, <code>month</code>, <code>year</code> +<li> the units can also be in plural forms +</ul> +<?= $ctx->{example}->('Set <code>Cache-Control: max-age=86400</code>', <<'EOT') +expires: 1 day +EOT +?> +<p> +You can also find an example that conditionally sets the header depending on the aspects of a request in <a href="configure/mruby.html#modifying-response">Modifying the Response section of the Mruby directives documentation</a>. +</p> +? }) + +? }) diff --git a/web/server/h2o/libh2o/srcdoc/configure/fastcgi_directives.mt b/web/server/h2o/libh2o/srcdoc/configure/fastcgi_directives.mt new file mode 100644 index 00000000..2e287088 --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/configure/fastcgi_directives.mt @@ -0,0 +1,114 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Configure", "FastCGI Directives")->(sub { + +<p> +This document describes the configuration directives of the FastCGI handler. +</p> +<p> +The configuration directives of the FastCGI handler can be categorized into two groups. +<code>Fastcgi.connect</code> and <code>fastcgi.spawn</code> define the address (or the process) to which the requests should be sent. +Other directives customize how the connections to the FastCGI processes should be maintained. +</p> + +<? +$ctx->{directive}->( + name => "fastcgi.connect", + levels => [ qw(path extension) ], + desc => q{The directive specifies the address at where the FastCGI daemon is running.}, +)->(sub { +?> +<p> +If the argument is a mapping, following properties are recognized. +<dl> +<dt><code>host</code> +<dd>name (or IP address) of the server running the FastCGI daemon (ignored if <code>type</code> is <code>unix</code>) +<dt><code>port</code> +<dd>TCP port number or path to the unix socket +<dt><code>type</code> +<dd>either <code>tcp</code> (default) or <code>unix</code> +</dl> +</p> +<p> +If the argument is a scalar, the value is considered as a TCP port number and the host is assumed to be <code>127.0.0.1</code>. +</p> +<?= $ctx->{example}->('Map <code>/app</code> to FastCGI daemon listening to <code>/tmp/fcgi.sock</code>', <<'EOT'); +hosts: + "example.com:80": + paths: + "/app": + fastcgi.connect: + port: /tmp/fcgi.sock + type: unix +EOT +?> +? }) + +<? +$ctx->{directive}->( + name => "fastcgi.spawn", + levels => [ qw(path extension) ], + desc => q{The directive specifies the command to start the FastCGI process manager.}, +)->(sub { +?> +<p> +In contrast to <code>fastcgi.connect</code> that connects to a FastCGI server running externally, this directive launches a FastCGI process manager under the control of H2O, and terminates it when H2O quits. +The argument is a <code>/bin/sh -c</code> expression to be executed when H2O boots up. +The HTTP server records the process id of the expression, and sends <code>SIGTERM</code> to the id when it exits. +</p> +<?= $ctx->{example}->('Map <code>.php</code> files to 10 worker processes of <code>/usr/local/bin/php-cgi</code>', <<'EOT'); +file.custom-handler: + extension: .php + fastcgi.spawn: "PHP_FCGI_CHILDREN=10 exec /usr/local/bin/php-cgi" +EOT +?> +<p> +As of version 1.4.0, the spawned process is run under the privileges of user specified by the <a href="configure/base_directives.html#user"><code>user</code></a> directive (in version 1.3.x, the FastCGI process was spawned under the privileges that spawned the H2O standalone server). +It is possible to specify a different user for running the FastCGI process, by providing a mapping that contains an attribute named <code>user</code> together with an attribute named <code>command</code>. +</p> +<?= $ctx->{example}->('Running FastCGI processes under user <code>fastcgi</code>', <<'EOT'); +file.custom-handler: + extension: .php + fastcgi.spawn: + command: "PHP_FCGI_CHILDREN=10 exec /usr/local/bin/php-cgi" + user: fastcgi +EOT +?> +? }) + +<? +$ctx->{directive}->( + name => "fastcgi.timeout.io", + levels => [ qw(global host path extension) ], + default => q{fastcgi.timeout.io: 30000}, + desc => q{Sets the I/O timeout of connections to the FastCGI process in milliseconds.}, +)->(sub {}); +?> + +<? +$ctx->{directive}->( + name => "fastcgi.timeout.keepalive", + levels => [ qw(global host path extension) ], + default => q{fastcgi.timeout.keepalive: 0}, + desc => 'Sets the keepl-alive timeout for idle connections in milliseconds.', +)->(sub { +?> +<p> +FastCGI connections will not be persistent if the value is set to zero (default). +</p> +? }) + +<? +$ctx->{directive}->( + name => "fastcgi.send-delegated-uri", + levels => [ qw(global host path extension) ], + default => q{fastcgi.send-delegated-uri: OFF}, + desc => 'Send the modified <code>HTTP_HOST</code> and <code>REQUEST_URI</code> being rewritten in case of internal redirect.', +)->(sub { +?> +<p> +In H2O, it is possible to perform internal redirects (a.k.a. delegations or URL rewrites) using <a href="configure/redirect_directives.html">the <code>redirect</code> directive</a> or <a href="configure/reproxy_directives.html">by returning <code>X-Reproxy-URL</code> headers</a> from web applications. +The directive specifies whether to send the original values to the FastCGI process (default), or if the rewritten values should be sent. +</p> +? }) + +? }) diff --git a/web/server/h2o/libh2o/srcdoc/configure/file_directives.mt b/web/server/h2o/libh2o/srcdoc/configure/file_directives.mt new file mode 100644 index 00000000..b56de065 --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/configure/file_directives.mt @@ -0,0 +1,244 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Configure", "File Directives")->(sub { + +<p> +This document describes the configuration directives of the file handler - a handler that for serving static files. +</p> +<p> +Two directives: <a href="configure/file_directives.html#file.dir"><code>file.dir</code></a> and <a href="configure/file_directives.html#file.file"><code>file.file</code></a> are used to define the mapping. +Other directives modify the behavior of the mappings defined by the two. +</p> + +<? +$ctx->{directive}->( + name => "file.custom-handler", + levels => [ qw(global host path) ], + desc => q{The directive maps extensions to a custom handler (e.g. FastCGI).}, +)->(sub { +?> +<p> +The directive accepts a mapping containing configuration directives that can be used at the <code>extension</code> level, together with a property named <code>extension</code> specifying a extension (starting with <code>.</code>) or a sequence of extensions to which the directives should be applied. +Only one handler must exist within the directives. +</p> +<?= $ctx->{example}->('Mapping PHP files to FastCGI', <<'EOT') +file.custom-handler: + extension: .php + fastcgi.connect: + port: /tmp/fcgi.sock + type: unix + +EOT +?> +? }) + +<? +$ctx->{directive}->( + name => "file.dir", + levels => [ qw(path) ], + desc => q{The directive specifies the directory under which should be served for the corresponding path.}, + see_also => render_mt(<<EOT), +<a href="configure/file_directives.html#file.dirlisting"><code>file.dirlisting</code></a>, +<a href="configure/file_directives.html#file.file"><code>file.file</code></a>, +<a href="configure/file_directives.html#file.index"><code>file.index</code></a> +EOT +)->(sub { +?> +<?= $ctx->{example}->('Serving files under different paths', <<'EOT') +paths: + "/": + file.dir: /path/to/doc-root + "/icons": + file.dir: /path/to/icons-dir +EOT +?> +? }) + +<? +$ctx->{directive}->( + name => "file.dirlisting", + levels => [ qw(global host path) ], + default => 'file.dirlisting: OFF', + desc => <<'EOT', +A boolean flag (<code>OFF</code>, or <code>ON</code>) specifying whether or not to send the directory listing in case none of the index files exist. +EOT + see_also => render_mt(<<EOT), +<a href="configure/file_directives.html#file.dir"><code>file.dir</code></a> +EOT +)->(sub {}); + +$ctx->{directive}->( + name => "file.etag", + levels => [ qw(global host path) ], + default => 'file.etag: ON', + desc => <<'EOT', +A boolean flag (<code>OFF</code>, or <code>ON</code>) specifying whether or not to send etags. +EOT +)->(sub {}); +?> + +<? +$ctx->{directive}->( + name => "file.file", + levels => [ qw(path) ], + desc => q{The directive maps a path to a specific file.}, + see_also => render_mt(<<EOT), +<a href="configure/file_directives.html#file.dir"><code>file.dir</code></a> +EOT + since => '2.0', +)->(sub { +?> +<?= $ctx->{example}->('Mapping a path to a specific file', <<'EOT') +paths: + /robots.txt: + file.file: /path/to/robots.txt +EOT +?> +? }) + +<? +$ctx->{directive}->( + name => "file.index", + levels => [ qw(global host path) ], + default => "file.index: [ 'index.html', 'index.htm', 'index.txt' ]", + desc => q{Specifies the names of the files that should be served when the client sends a request against the directory.}, + see_also => render_mt(<<EOT), +<a href="configure/file_directives.html#file.dir"><code>file.dir</code></a> +EOT +)->(sub { +?> +<p> +The sequence of filenames are searched from left to right, and the first file that existed is sent to the client. +</p> +? }) + +<? +$ctx->{directive}->( + name => "file.mime.addtypes", + levels => [ qw(global host path) ], + see_also => render_mt(<<'EOT'), +<a href="configure/compress_directives.html#compress"><code>compress</code></a>, +<a href="configure/http2_directives.html#http2-casper"><code>http2-casper</code></a>, +<a href="configure/http2_directives.html#http2-reprioritize-blocking-assets"><code>http2-reprioritize-blocking-assets</code></a> +EOT + desc => q{The directive modifies the MIME mappings by adding the specified MIME type mappings.}, +)->(sub { +?> +<?= $ctx->{example}->('Adding MIME mappings', <<'EOT') +file.mime.addtypes: + "application/javascript": ".js" + "image/jpeg": [ ".jpg", ".jpeg" ] +EOT +?> +<p> +The default mappings is hard-coded in <a href="https://github.com/h2o/h2o/blob/master/lib/handler/mimemap/defaults.c.h">lib/handler/mimemap/defaults.c.h</a>. +</p> +<p> +It is also possible to set certain attributes for a MIME type. +The example below maps <code>.css</code> files to <code>text/css</code> type, setting <code>is_compressible</code> flag to <code>ON</code> and <code>priority</code> to highest. +</p> + +<?= $ctx->{example}->('Setting MIME attributes', <<'EOT') +file.mime.settypes: + "text/css": + extensions: [".css"] + is_compressible: yes + priority: highest +EOT +?> + +<p> +Following attributes are recognized. +</p> + +<table> +<tr><th>Attribute<th>Possible Values<th>Description +<tr><td><code>is_compressible</code><td><code>ON</code>, <code>OFF</code><td>if content is compressible +<tr><td><code>priority</code><td><code>highest<code>, <code>normal</code><td>send priority of the content +</table> + +<p> +The <code>priority</code> attribute affects how the HTTP/2 protocol implementation handles the request. +For detail, please refer to the HTTP/2 directives listed in the <i>see also</i> section below. +By default, mime-types for CSS and JavaScript files are the only ones that are given <code>highest</code> priority. +</p> + +? }) + +<? +$ctx->{directive}->( + name => "file.mime.removetypes", + levels => [ qw(global host path) ], + desc => q{Removes the MIME mappings for specified extensions supplied as a sequence of extensions.}, +)->(sub { +?> +<?= $ctx->{example}->('Removing MIME mappings', <<'EOT') +file.mime.removetypes: [ ".jpg", ".jpeg" ] +EOT +?> +? }) + +<? +$ctx->{directive}->( + name => "file.mime.setdefaulttype", + levels => [ qw(global host path) ], + default => q{file.mime.setdefaulttype: "application/octet-stream"}, + desc => q{Sets the default MIME-type that is used when an extension does not exist in the MIME mappings}, +)->(sub {}) +?> + +<? +$ctx->{directive}->( + name => "file.mime.settypes", + levels => [ qw(global host path) ], + desc => q{Resets the MIME mappings to given mapping.}, +)->(sub { +?> +<?= $ctx->{example}->('Resetting the MIME mappings to minimum', <<'EOT') +file.mime.settypes: + "text/html": [ ".html", ".htm" ] + "text/plain": ".txt" +EOT +?> +? }) + +<? +$ctx->{directive}->( + name => "file.send-compressed", + levels => [ qw(global host path) ], + default => q{file.send-compressed: OFF}, + see_also => render_mt(<<'EOT'), +<a href="configure/compress_directives.html#compress"><code>compress</code></a> +EOT + since => '2.0', + desc => <<'EOT', +A flag indicating how a pre-compressed file should be served. +EOT +)->(sub { +?> +<p> +If set to <code>ON</code>, the handler looks for a file with <code>.br</code> or <code>.gz</code> appended and sends the file, if the client is capable of transparently decoding a <a href="https://datatracker.ietf.org/doc/draft-alakuijala-brotli/">brotli</a> or <a href="https://tools.ietf.org/html/rfc1952">gzip</a>-encoded response. +For example, if a client requests a file named <code>index.html</code> with <code>Accept-Encoding: gzip</code> header and if <code>index.html.gz</code> exists, the <code>.gz</code> file is sent as a response together with a <code>Content-Encoding: gzip</code> response header. +</p> +<p> +If set to <code>OFF</code>, the handler always serves the file specified by the client. +</p> +<p> +Starting from version 2.2, <code>gunzip</code> is also supported. +If set, the handler acts identical to when the value was set to <code>ON</code>. +In addition, the handler will send an uncompressed response by dynamically decompressing the <code>.gz</code> file if the client and the server failed to agree on using a pre-compressed file as the response and if a non-compressed file was not found. +The option is useful when conserving disk space is important; it is possible to remove the uncompressed files in place for gzipped ones. +</p> +? }) + +<? +$ctx->{directive}->( + name => "file.send-gzip", + levels => [ qw(global host path) ], + desc => <<'EOT', +Obsoleted in 2.0. +Synonym of <a href="configure/file_directives.html#file.send-compressed"><code>file.send-compressed</code></a>. +EOT +)->(sub {}) +?> + +? }) diff --git a/web/server/h2o/libh2o/srcdoc/configure/headers_directives.mt b/web/server/h2o/libh2o/srcdoc/configure/headers_directives.mt new file mode 100644 index 00000000..6c2af078 --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/configure/headers_directives.mt @@ -0,0 +1,84 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Configure", "Headers Directives")->(sub { + +<p> +This document describes the configuration directives of the headers handler. +</p> + +<? +$ctx->{directive}->( + name => "header.add", + levels => [ qw(global host path extension) ], + desc => q{Adds a new header line to the response headers, regardless if a header with the same name already exists.}, +)->(sub { +?> +<div class="example"> +<div class="caption">Example. Setting the <code>Set-Cookie</code> header</div> +<pre><code>header.add: "Set-Cookie: test=1"</code></pre> +</div> +? }) + +<? +$ctx->{directive}->( + name => "header.append", + levels => [ qw(global host path extension) ], + desc => <<'EOT', +Adds a new header line, or appends the value to the existing header with the same name, separated by <code>,</code>. +EOT +)->(sub {}); +?> + +<? +$ctx->{directive}->( + name => "header.merge", + levels => [ qw(global host path extension) ], + desc => <<'EOT', +Adds a new header line, or merges the value to the existing header of comma-separated values. +EOT +)->(sub { +?> +<p> +The following example sets the <code>must-revalidate</code> attribute of the <code>Cache-Control</code> header when and only when the attribute is not yet being set. +</p> +<?= $ctx->{example}->('Setting the <code>must-revalidate</code> attribute', <<'EOT') +header.merge: "Cache-Control: must-revalidate" +EOT +?> +? }) + +<? +$ctx->{directive}->( + name => "header.set", + levels => [ qw(global host path extension) ], + desc => q{Sets a header line, removing headers with the same name if exists.}, +)->(sub { +?> +<?= $ctx->{example}->('Setting the <code>X-Content-Type-Options: nosniff</code> header', <<'EOT') +header.set: "X-Content-Type-Options: nosniff" +EOT +?> +? }) + +<? +$ctx->{directive}->( + name => "header.setifempty", + levels => [ qw(global host path extension) ], + desc => <<'EOT', +Sets a header line when and only when a header with the same name does not already exist. +EOT +)->(sub {}); + +<? +$ctx->{directive}->( + name => "header.unset", + levels => [ qw(global host path extension) ], + desc => q{Removes headers with given name.}, +)->(sub { +?> +<?= $ctx->{example}->('Removing the <code>X-Powered-By</code> header', <<'EOT') +header.unset: "X-Powered-By" +EOT +?> +? }) + +? }) diff --git a/web/server/h2o/libh2o/srcdoc/configure/http1_directives.mt b/web/server/h2o/libh2o/srcdoc/configure/http1_directives.mt new file mode 100644 index 00000000..77894acc --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/configure/http1_directives.mt @@ -0,0 +1,24 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Configure", "HTTP/1 Directives")->(sub { + +<p> +This document describes the configuration directives for controlling the HTTP/1 protocol handler. +</p> + +<? +$ctx->{directive}->( + name => "http1-request-timeout", + levels => [ qw(global) ], + default => 'http1-request-timeout: 10', + desc => q{Timeout for incoming requests in seconds.}, +)->(sub {}); + +$ctx->{directive}->( + name => "http1-upgrade-to-http2", + levels => [ qw(global) ], + default => 'http1-upgrade-to-http2: ON', + desc => q{Boolean flag (<code>ON</code> or <code>OFF</code>) indicating whether or not to allow upgrade to HTTP/2.}, +)->(sub {}); +?> + +? }) diff --git a/web/server/h2o/libh2o/srcdoc/configure/http2_directives.mt b/web/server/h2o/libh2o/srcdoc/configure/http2_directives.mt new file mode 100644 index 00000000..7c2fc26e --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/configure/http2_directives.mt @@ -0,0 +1,356 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Configure", "HTTP/2 Directives")->(sub { + +<p> +H2O provides one of the world's most sophisticated HTTP/2 protocol implementation, including following features. +</p> + +<h3 id="prioritization">Prioritization</h3> + +<p> +H2O is one of the few servers that fully implement prioritization of HTTP responses conformant to what is defined in the <a href="https://tools.ietf.org/html/rfc7540">HTTP/2 specification</a>. +The server implements a O(1) scheduler that determines which HTTP response should be sent to the client, per every 16KB chunk. +</p> +<p> +Unfortunately, some web browsers fail to specify response priorities that lead to best end-user experience. +H2O is capable of detecting such web browsers, and if it does, uses server-driven prioritization; i.e. send responses with certain MIME-types before others. +</p> +<p> +It is possible to tune or turn off server-driven prioritization using directives: <a href="configure/file_directives.html#file.mime.addtypes"><code>file.mime.addtypes</code></a>, <a href="configure/http2_directives.html#http2-reprioritize-blocking-assets"><code>http2-reprioritize-blocking-assets</code></a>. +</p> +<p> +See also: +<ul> +<li><a href="benchmarks.html#download-timings">Download Timings Benchmark</a> +<li><a href="http://blog.kazuhooku.com/2015/06/http2-and-h2o-improves-user-experience.html">HTTP/2 (and H2O) improves user experience over HTTP/1.1 or SPDY</a> +</ul> +</p> + +<h3 id="server-push">Server push</h3> + +<p> +H2O recognizes <code>link</code> headers with <a href="https://w3c.github.io/preload/">preload</a> keyword sent by a backend application server (reverse proxy or FastCGI) or an mruby handler, and pushes the designated resource to a client. +</p> +<?= $ctx->{example}->('A link response header triggering HTTP/2 push', <<'EOT') +link: </assets/jquery.js>; rel=preload; as=script +EOT +?> + +<p>When the HTTP/2 driver of H2O recognizes a <code>link</code> response header with <code>rel=preload</code> attribute set, and if all of the following conditions are met, the specified resource is pushed to the client. +</p> +<ul> +<li>configuration directive <a href="configure/http2_directives.html#http2-push-preload">http2-push-preload</a> is not set to <code>OFF</code></li> +<li>the <code>link</code> header does not have the <code>nopush</code> attribute set</li> +<li>the <code>link</code> header is <i>not</i> part of a pushed response</li> +<li>the client does not disable HTTP/2 push</li> +<li>number of the pushed responses in-flight is below the negotiated threshold</li> +<li>authority of the resource specified is equivalent to the request that tried to trigger the push</li> +<li>(for handlers that return the status code synchronously) the status code of the response to be pushed does not indicate an error (i.e. 4xx or 5xx)</li> +</ul> +<p> +The server also provides a mechanism to track the clients' cache state via cookies, and to push the resources specified with the <code>link</code> header only when it does not exist within the clients' cache. For details, please refer to the documentation of <a href="configure/http2_directives.html#http2-casper"><code>http2-casper</code></a> configuration directive. +</p> +<p> +When a resource is pushed, the priority is determined using the <a href="configure/file_directives.html#file.mime.addtypes"><code>priority</code> attribute</a> of the MIME-type configuration. If the priority is set to <code>highest</code> then the resource will be sent to the client before anything else; otherwise the resource will be sent to client after the main content, as per defined by the HTTP/2 specification. +</p> +<p> +HTTP/1.1 allows a server to send an informational response (see <a href="https://tools.ietf.org/html/rfc7231#section-6.2" target="_blank">RFC 7230 section 6.2</a>) before sending the final response. +Starting from version 2.1, web applications can take advantage of the informational response to initiate HTTP/2 pushes before starting to process the request. +The following example shows how such responses would look like. +</p> +<?= $ctx->{example}->('100 response with link headers', <<'EOT') +HTTP/1.1 100 Continue +Link: </assets/style.css>; rel=preload; as=style +Link: </assets/jquery.js>; rel=preload; as=script + +HTTP/1.1 200 OK +Content-Type: text/html; charset=utf-8 + +<!doctype html> +<html> +<head> +<link rel="stylesheet" type="text/css" href="/assets/style.css"> +<script type="text/javascript" src="/assets/jquery.js"></scrrpt> +... +EOT +?> +<p> +Pushed responses will have <code>x-http2-push: pushed</code> header set; by looking for the header, it is possible to determine if a resource has been pushed. +It is also possible to log the value in the <a href="configure/access_log_directives.html#access-log">access log</a> by specifying <code>%{x-http2-push}o</code>, push responses but cancelled by CASPER will have the value of the header logged as <code>cancelled</code>. +</p> +<p> +See also: +<ul> +<li><a href="http://blog.kazuhooku.com/2015/12/optimizing-performance-of-multi-tiered.html">Optimizing performance of multi-tier web applications using HTTP/2 push</a> +</ul> +</p> + +<h3 id="latency-optimization">Latency Optimization</h3> + +<p> +When using HTTP/2, a client often issues high-priority requests (e.g. requests for CSS and JavaScript files that block the rendering) while a lower-priority response (e.g. HTML) is in flight. +In such case, it is desirable for a server to switch to sending the response of the high-priority requests as soon as it observes the requests. +</p> +<p> +In order to do so, send buffer of the TCP/IP stack should be kept empty except for the packets in-flight, and size of the TLS records must be small enough to avoid head-of-line blocking. +The downside is that obeying the requirement increases the interaction between the server process and kernel, which result in consumption of more CPU cycles and slightly increased latency. +</p> +<p> +Starting from version 2.1, H2O provides directives that lets the users tune how the TCP/IP stack is used depending on the observed RTT, CWND, and the additional latency imposed by the interaction between the server and the OS. +</p> +<p> +For TCP/IP connections with greater RTT and smaller CWND than the configured threshold, the server will try to keep the size of HTTP/2 frames unsent as small as possible so that it can switch to sending a higher-priority response. +Benchmarks suggest that users can expect in average 1 RTT reduction when this optimization is enabled. +For connections that do not meet the criteria, the server will utilize the TCP/IP stack in ordinary ways. +</p> +<p> +The default values of the thresholds have been chosen that the optimization will come into action for mobile and long-distance networks but not when a proxy exists on the network. +</p> +<p> +The optimization is supported only on Linux and OS X. The two are the operating systems that provide access to <code>TCP_INFO</code> and an interface to adjust the size of the unsent buffer (<code>TCP_NOTSENT_LOWAT</code>). +</p> +<p> +Please refer to the documentation of the directives below to configure the optimization: +<ul> +<li><a href="configure/http2_directives.html#http2-latency-optimization-min-rtt"><code>http2-latency-optimization-min-rtt</code></a></li> +<li><a href="configure/http2_directives.html#http2-latency-optimization-max-additional-delay"><code>http2-latency-optimization-max-additional-delay</code></a></li> +<li><a href="configure/http2_directives.html#http2-latency-optimization-max-cwnd"><code>http2-latency-optimization-max-cwnd</code></a></li> +</ul> +</p> +<p> +See also: +<ul> +<li><a href="http://www.slideshare.net/kazuho/reorganizing-website-architecture-for-http2-and-beyond">Reorganizing Website Architecture for HTTP/2 and Beyond</a> pp.14-21</li> +</ul> +</p> + +<p> +The following describes the configuration directives for controlling the HTTP/2 protocol handler. +</p> + +<? +$ctx->{directive}->( + name => "http2-casper", + levels => [ qw(global host) ], + default => "http2-casper: OFF", + see_also => render_mt(<<'EOT'), +<a href="configure/file_directives.html#file.mime.addtypes"><code>file.mime.addtypes</code></a>, +<a href="https://github.com/h2o/h2o/issues/421">issue #421</a> +EOT + desc => <<'EOT', +Configures CASPer (cache-aware server-push). +EOT +)->(sub { +?> +<p> +When enabled, H2O maintains a fingerprint of the web browser cache, and cancels server-push suggested by the handlers if the client is known to be in possession of the content. +The fingerprint is stored in a cookie named <code>h2o_casper</code> using <a href="https://www.imperialviolet.org/2011/04/29/filters.html">Golomb-compressed sets</a> (a compressed encoding of <a href="https://en.wikipedia.org/wiki/Bloom_filter">Bloom filter</a>). +</p> +<p> +If the value is <code>OFF</code>, the feature is disabled. +Push requests (made by the handlers through the use of <code>Link: rel=preload</code> header) are processed regardless of whether if client already has the responses in its cache. +If the value is <code>ON</code>, the feature is enabled with the defaults value specified below. +If the value is mapping, the feature is enabled, recognizing the following attributes. +<dl> +<dt>capacity-bits: +<dd>number of bits used for the fingerprinting. +Roughly speaking, the number of bits should be <code>log2(1/P * number-of-assets-to-track)</code> where P being the probability of false positives. +Default is <code>13</code>, enough for tracking about 100 asset files with 1/100 chance of false positives (i.e. <code>log2(100 * 100) =~ 13</code>). +<dt>tracking-types: +<dd>specifies the types of the content tracked by casper. +If omitted or set to <code>blocking-assets</code>, maintains fingerprint (and cancels server push) for resources with mime-type of <a href="configure/file_directives.html#file.mime.addtypes"><code>highest</code></a> priority. +If set to <code>all</code>, tracks all responses. +</dl> +</p> +It should be noted that the size of the cookie will be <code>log2(P) * number-of-assets-being-tracked</code> bits multiplied by the overhead of Base 64 encoding (<code>4/3</code>). +Therefore with current cookie-based implementation, it is necessary in many cases to restrict the resources being tracked to those have significant effect to user-perceived response time. +</p> + +<?= $ctx->{example}->('Enabling CASPer', <<'EOT') +http2-casper: ON + +# `ON` is equivalent to: +# http2-casper: +# capacity-bits: 13 +# tracking-types: blocking-assets +EOT +?> + +? }); + +<? +my $spec_url = "https://tools.ietf.org/html/draft-benfield-http2-debug-state-01"; +$ctx->{directive}->( + name => "http2-debug-state", + levels => [ qw(host) ], + see_also => render_mt(<<"EOT"), +<a href=\"$spec_url\">HTTP/2 Implementation Debug State (draft-01)</a> +EOT + desc => <<"EOT", +A directive to turn on the <a href=\"$spec_url\">HTTP/2 Implementation Debug State</a>. +EOT +)->(sub { +?> + +<p> +This experimental feature serves a JSON document at the fixed path <code>/.well-known/h2/state</code>, which describes an internal HTTP/2 state of the H2O server. +To know the details about the response fields, please see <a href="<?= $spec_url ?>">the spec</a>. +This feature is only for developing and debugging use, so it's highly recommended that you disable this setting in the production environment. +</p> + +<p> +The value of this directive specifies the property set contained in the response. Available values are <code>minimum</code> or <code>hpack</code>. +If <code>hpack</code> is specified, the response will contain the internal hpack state of the same connection. +If <code>minimum</code> is specified, the response doesn't contain the internal hpack state. +</p> + +<p> +In some circumstances, there may be a risk of information leakage on providing an internal hpack state. For example, the case that some proxies exist between the client and the server, and they share the connections among the clients. +Therefore, you should specify <code>hpack</code> only when the server runs in the environments you can completely control. +</p> + +<p> +This feature is considered experimental yet. +For now, the implementation conforms to the version draft-01 of the specification. +</p> + +? }); + +<? +$ctx->{directive}->( + name => "http2-idle-timeout", + levels => [ qw(global) ], + default => 'http2-idle-timeout: 10', + desc => <<'EOT', +Timeout for idle connections in seconds. +EOT +)->(sub {}); + +$ctx->{directive}->( + name => "http2-max-concurrent-requests-per-connection", + levels => [ qw(global) ], + default => 'http2-max-concurrent-requests-per-connection: 100', + desc => <<'EOT', +Maximum number of requests to be handled concurrently within a single HTTP/2 connection. +EOT +)->(sub { +?> +<p> +The value cannot exceed 256. +</p> +? }) + +<? +$ctx->{directive}->( + name => "http2-latency-optimization-min-rtt", + levels => [ qw(global) ], + since => '2.1', + default => 'http2-latency-optimization-min-rtt: 50', + desc => << 'EOT', +Minimum RTT (in milliseconds) to enable <a href="configure/http2_directives.html#latency-optimization">latency optimization</a>. +EOT +)->(sub { +?> +<p> +Latency optimization is disabled for TCP connections with smaller RTT (round-trip time) than the specified value. +Otherwise, whether if the optimization is used depends on other parameters. +</p> +<p> +Setting this value to 4294967295 (i.e. <code>UINT_MAX</code>) effectively disables the optimization. +</p> +? }) + +<? +$ctx->{directive}->( + name => "http2-latency-optimization-max-additional-delay", + levels => [ qw(global) ], + since => '2.1', + default => 'http2-latency-optimization-max-additional-delay: 0.1', + desc => << 'EOT', +Maximum additional delay (as the ratio to RTT) permitted to get <a href="configure/http2_directives.html#latency-optimization">latency optimization</a> activated. +EOT +)->(sub { +?> +<p> +Latency optimization is disabled if the additional delay imposed by the interaction between the OS and the TCP/IP stack is estimated to be greater than the given threshold. +Otherwise, whether if the optimization is used depends on other parameters. +</p> +? }) + +<? +$ctx->{directive}->( + name => "http2-latency-optimization-max-cwnd", + levels => [ qw(global) ], + since => '2.1', + default => 'http2-latency-optimization-max-cwnd: 65535', + desc => << 'EOT', +Maximum size (in octets) of CWND to get <a href="configure/http2_directives.html#latency-optimization">latency optimization</a> activated. +EOT +)->(sub { +?> +<p> +CWND is a per-TCP-connection variable that represents the number of bytes that can be sent within 1 RTT. +</p> +<p> +The server will not use or stop using latency optimization mode if CWND becomes greater than the configured value. +In such case, average size of HTTP/2 frames buffered unsent will be slightly above the <a href="https://www.kernel.org/doc/Documentation/networking/ip-sysctl.txt" target="_blank"><code>tcp_notsent_lowat</code></a> sysctl value. +</p> +?> +? }) + +<? +$ctx->{directive}->( + name => "http2-push-preload", + levels => [ qw(global host) ], + since => '2.1', + default => 'http2-push-preload: ON', + desc => << 'EOT', +A boolean flag (<code>ON</code> or <code>OFF</code>) indicating whether if the server should push resources when observing a <code>link: rel=preload</code> header. +EOT +)->(sub { +?> +? }) + +<? +$ctx->{directive}->( + name => "http2-reprioritize-blocking-assets", + levels => [ qw(global) ], + default => 'http2-reprioritize-blocking-assets: ON', + see_also => render_mt(<<'EOT'), +<a href="configure/file_directives.html#file.mime.addtypes"><code>file.mime.addtypes</code></a>, +<a href="http://blog.kazuhooku.com/2015/06/http2-and-h2o-improves-user-experience.html">HTTP/2 (and H2O) improves user experience over HTTP/1.1 or SPDY</a> +EOT + desc => <<'EOT', +A boolean flag (<code>ON</code> or <code>OFF</code>) indicating if the server should send contents with <code>highest</code> priority before anything else. +EOT +)->(sub { +?> +<p> +To maximize the user-perceived responsiveness of a web page, it is essential for the web server to send blocking assets (i.e. CSS and JavaScript files in <code><HEAD></code>) before any other files such as images. +HTTP/2 provides a way for web browsers to specify such priorities to the web server. +However, as of Sep. 2015, no major web browsers except Mozilla Firefox take advantage of the feature. +</p> +<p> +This option, when enabled, works as a workaround for such web browsers, thereby improving experience of users using the web browsers. +</p> +<p> +Technically speaking, it does the following: +<ul> +<li>if the client uses dependency-based prioritization, do not reprioritize +<li>if the client does not use dependency-based prioritization, send the contents of which their types are given <a href="configure/file_directives.html#file.mime.addtypes"><code>highest</code></a> priority before any other responses +</ul> +</p> +? }); + +<? +$ctx->{directive}->( + name => "http2-graceful-shutdown-timeout", + levels => [ qw(global) ], + default => 'http2-graceful-shutdown-timeout: 0', + desc => <<'EOT', +A timeout in seconds. How long to wait before closing the connection on graceful shutdown. Setting the timeout to <code>0</code> deactivates the feature: H2O will wait for the peer to close the connections. +EOT +)->(sub {}); +?> + +? }) diff --git a/web/server/h2o/libh2o/srcdoc/configure/mruby.mt b/web/server/h2o/libh2o/srcdoc/configure/mruby.mt new file mode 100644 index 00000000..99affa81 --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/configure/mruby.mt @@ -0,0 +1,199 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Configure", "Using Mruby")->(sub { + +<p> +<a href="https://github.com/mruby/mruby">mruby</a> is a lightweight implementation of the Ruby programming language. +With H2O, users can implement their own request handling logic using mruby, either to generate responses or to fix-up the request / response. +</p> + +<h3 id="programming-interface">Rack-based Programming Interface</h3> + +<p> +The interface between the mruby program and the H2O server is based on <a href="http://www.rubydoc.info/github/rack/rack/master/file/SPEC">Rack interface specification</a>. +Below is a simple configuration that returns <i>hello world</i>. +</p> + +<?= $ctx->{example}->('Hello-world in mruby', <<'EOT') +paths: + "/": + mruby.handler: | + Proc.new do |env| + [200, {'content-type' => 'text/plain'}, ["Hello world\n"]] + end +EOT +?> + +<p> +It should be noted that as of H2O version 1.7.0, there are limitations when compared to ordinary web application server with support for Rack such as Unicorn: +<ul> +<li>no libraries provided as part of Rack is available (only the interface is compatible) +</ul> +</p> + +<p> +In addition to the Rack interface specification, H2O recognizes status code <code>399</code> which can be used to delegate request to the next handler. +The feature can be used to implement access control and response header modifiers. +</p> + +<h3 id="access-control">Access Control</h3> + +<p> +By using the <code>399</code> status code, it is possible to implement access control using mruby. +The example below restricts access to requests from <code>192.168.</code> private address. +</p> + +<?= $ctx->{example}->('Restricting access to 192.168.', <<'EOT') +paths: + "/": + mruby.handler: | + lambda do |env| + if /\A192\.168\./.match(env["REMOTE_ADDR"]) + return [399, {}, []] + end + [403, {'content-type' => 'text/plain'}, ["access forbidden\n"]] + end +EOT +?> + +<p> +Support for <a href="configure/basic_auth.html">Basic Authentication</a> is also provided by an mruby script. +</p> + +<h3 id="delegating-request">Delegating the Request</h3> + +<p> +When enabled using the <a href="configure/reproxy_directives.html#reproxy"><code>reproxy</code></a> directive, it is possible to delegate the request from the mruby handler to any other handler. +</p> +<p> +<?= $ctx->{example}->('Rewriting URL with delegation', <<'EOT') +paths: + "/": + mruby.handler: | + lambda do |env| + if /\/user\/([^\/]+)/.match(env["PATH_INFO"]) + return [307, {"x-reproxy-url" => "/user.php?user=#{$1}"}, []] + end + return [399, {}, []] + end +EOT +?> + +<h3 id="modifying-response">Modifying the Response</h3> + +<p> +When the mruby handler returns status code <code>399</code>, H2O delegates the request to the next handler while preserving the headers emitted by the handler. +The feature can be used to add extra headers to the response. +</p> +<p> +For example, the following example sets <code>cache-control</code> header for requests against <code>.css</code> and <code>.js</code> files. +</p> + +<?= $ctx->{example}->('Setting cache-control header for certain types of files', <<'EOT') +paths: + "/": + mruby.handler: | + Proc.new do |env| + headers = {} + if /\.(css|js)\z/.match(env["PATH_INFO"]) + headers["cache-control"] = "max-age=86400" + end + [399, headers, []] + end + file.dir: /path/to/doc-root +EOT +?> + +<p> +Or in the example below, the handler triggers <a href="configure/http2_directives.html#server-push">HTTP/2 server push</a> with the use of <code>Link: rel=preload</code> headers, and then requests a FastCGI application to process the request. +</p> + +<?= $ctx->{example}->('Pushing asset files', <<'EOT') +paths: + "/": + mruby.handler: | + Proc.new do |env| + push_paths = [] + # push css and js when request is to dir root or HTML + if /(\/|\.html)\z/.match(env["PATH_INFO"]) + push_paths << ["/css/style.css", "style"] + push_paths << ["/js/app.js", "script"] + end + [399, push_paths.empty? ? {} : {"link" => push_paths.map{|p| "<#{p[0]}>; rel=preload; as=#{p[1]}"}.join("\n")}, []] + end + fastcgi.connect: ... +EOT +?> + +<h3 id="http-client">Using the HTTP Client</h3> + +<p> +Starting from version 1.7, a HTTP client API is provided. +HTTP requests issued through the API will be handled asynchronously; the client does not block the event loop of the HTTP server. +</p> + +<?= $ctx->{example}->('Mruby handler returning the response of http://example.com', <<'EOT') +paths: + "/": + mruby.handler: | + Proc.new do |env| + req = http_request("http://example.com") + status, headers, body = req.join + [status, headers, body] + end +EOT +?> + +<p> +<code>http_request</code> is the method that issues a HTTP request. +</p> +<p> +The method takes two arguments. +First argument is the target URI. +Second argument is an optional hash; <code>method</code> (defaults to <code>GET</code>), <code>header</code>, <code>body</code> attributes are recognized. +</p> +<p> +The method returns a promise object. +When <code>#join</code> method of the promise is invoked, a three-argument array containing the status code, response headers, and the body is returned. +The response body is also a promise. +Applications can choose from three ways when dealing with the body: a) call <code>#each</code> method to receive the contents, b) call <code>#join</code> to retrieve the body as a string, c) return the object as the response body of the mruby handler. +</p> +<p> +The header and the body object passed to <code>http_request</code> should conform to the requirements laid out by the Rack specification for request header and request body. +The response header and the response body object returned by the <code>#join</code> method of the promise returned by <code>http_request</code> conforms to the requirements of the Rack specification. +</p> +<p> +Since the API provides an asynchronous HTTP client, it is possible to effectively issue multiple HTTP requests concurrently and merge them into a single response. +</p> +<p> +When HTTPS is used, servers are verified using the properties of <a href="configure/proxy_directives.html#proxy.ssl.cafile"><code>proxy.ssl.cafile</code></a> and <a href="configure/proxy_directives.html#proxy.ssl.verify-peer"><code>proxy.ssl.verify-peer</code></a> specified at the global level. +</p> + +<h3 id="logging-arbitrary-variable">Logging Arbitrary Variable</h3> + +<p> +In version 2.3, it is possible from mruby to set and log an arbitrary-named variable that is associated to a HTTP request. +A HTTP response header that starts with <code>x-fallthru-set-</code> is handled specially by the H2O server. Instead of sending the header downstream, the server accepts the value as a request environment variable, taking the suffix of the header name as the name of the variable. +</p> +<p> +This example shows how to read request data, parse json and then log data from mruby. +</p> + +<?= $ctx->{example}->('Logging the content of a POST request via request environment variable', <<'EOT') +paths: + "/": + mruby.handler: | + Proc.new do |env| + input = env["rack.input"] ? env["rack.input"].read : '{"default": "true"}' + parsed_json = JSON.parse(input) + parsed_json["time"] = Time.now.to_i + logdata = parsed_json.to_s + [204, {"x-fallthru-set-POSTDATA" => logdata}, []] + end + access-log: + path: /path/to/access-log.json + escape: json + format: '{"POST": %{POSTDATA}e}' +EOT +?> + +? }) diff --git a/web/server/h2o/libh2o/srcdoc/configure/mruby_directives.mt b/web/server/h2o/libh2o/srcdoc/configure/mruby_directives.mt new file mode 100644 index 00000000..e1d0e2fc --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/configure/mruby_directives.mt @@ -0,0 +1,58 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Configure", "Mruby Directives")->(sub { + +<p> +The following are the configuration directives of the mruby handler. +Please refer to <a href="configure/mruby.html">Using mruby</a> to find out how to write handlers using mruby. +</p> + +<? +$ctx->{directive}->( + name => "mruby.handler", + levels => [ qw(path) ], + see_also => render_mt(<<'EOT'), +<a href="configure/mruby_directives.html#mruby.handler-file"><code>mruby.handler-file</code></a> +EOT + desc => <<'EOT', +Upon start-up evaluates given mruby expression, and uses the returned mruby object to handle the incoming requests. +EOT +)->(sub { +?> + +<?= $ctx->{example}->('Hello-world in mruby', <<'EOT') +mruby.handler: | + Proc.new do |env| + [200, {'content-type' => 'text/plain'}, ["Hello world\n"]] + end +EOT +?> + +<p> +Note that the provided expression is evaluated more than once (typically for every thread that accepts incoming connections). +</p> +? }) + +<? +$ctx->{directive}->( + name => "mruby.handler-file", + levels => [ qw(path) ], + see_also => render_mt(<<'EOT'), +<a href="configure/mruby_directives.html#mruby.handler"><code>mruby.handler</code></a> +EOT + desc => <<'EOT', +Upon start-up evaluates given mruby file, and uses the returned mruby object to handle the incoming requests. +EOT +)->(sub { +?> + +<?= $ctx->{example}->('Hello-world in mruby', <<'EOT') +mruby.handler-file: /path/to/my-mruby-handler.rb +EOT +?> + +<p> +Note that the provided expression is evaluated more than once (typically for every thread that accepts incoming connections). +</p> +? }) + +? }) diff --git a/web/server/h2o/libh2o/srcdoc/configure/proxy_directives.mt b/web/server/h2o/libh2o/srcdoc/configure/proxy_directives.mt new file mode 100644 index 00000000..bea7e00b --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/configure/proxy_directives.mt @@ -0,0 +1,236 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Configure", "Proxy Directives")->(sub { + +<p> +Proxy module is the reverse proxy implementation for H2O - it implements a HTTP client that forwards a HTTP request to an upstream server. +</p> +<p> +When forwarding the requests, the module sets following request headers: +<ul> +<li><a href="https://tools.ietf.org/html/rfc7230#section-5.7.1">via</a></li> +<li><a href="http://docs.aws.amazon.com/ElasticLoadBalancing/latest/DeveloperGuide/x-forwarded-headers.html#x-forwarded-for">x-forwarded-for</a></li> +<li><a href="http://docs.aws.amazon.com/ElasticLoadBalancing/latest/DeveloperGuide/x-forwarded-headers.html#x-forwarded-proto">x-forwarded-proto</a></li> +</ul> +</p> +<p> +The HTTP client only supports HTTP/1. +Support for HTTPS has been introduced in version 2.0. +</p> +<p> +Following sections describe the configuration directives defined for the module. +</p> + +<? +$ctx->{directive}->( + name => "proxy.reverse.url", + levels => [ qw(path) ], + desc => q{Forwards the requests to the specified URL, and proxies the response.}, +)->(sub { +?> +<?= $ctx->{example}->(q{Forwarding the requests to application server running on <code>127.0.0.1:8080</code>}, <<'EOT') +proxy.reverse.url: "http://127.0.0.1:8080/" +EOT +?> +<p> +If you want load balancing multiple backends, replace 127.0.0.1 with hostname which returns IP addresses via DNS or /etc/hosts. +</p> +<p> +In addition to TCP/IP over IPv4 and IPv6, the proxy handler can also connect to an HTTP server listening to a Unix socket. +Path to the unix socket should be surrounded by square brackets, and prefixed with <code>unix:</code> (e.g. <code>http://[unix:/path/to/socket]/path</code>). +</p> + +? }) + +<? +$ctx->{directive}->( + name => "proxy.preserve-host", + levels => [ qw(global host path extension) ], + default => q{proxy.preserve-host: OFF}, + desc => q{A boolean flag (<code>ON</code> or <code>OFF</code>) designating whether or not to pass <code>Host</code> header from incoming request to upstream.}, +)->(sub {}); +?> + +<? +$ctx->{directive}->( + name => "proxy.preserve-x-forwarded-proto", + levels => [ qw(global) ], + since => "2.0", + default => q{proxy.preserve-x-forwarded-proto: OFF}, + desc => "A boolean flag(<code>ON</code> or <code>OFF</code>) indicating if the server preserve the received <code>x-forwarded-proto</code> request header.", +)->(sub { +?> +<p> +By default, when transmitting a HTTP request to an upstream HTTP server, H2O removes the received <code>x-forwarded-proto</code> request header and sends its own, as a precaution measure to prevent an attacker connecting through HTTP to lie that they are connected via HTTPS. +However in case H2O is run behind a trusted HTTPS proxy, such protection might not be desirable, and this configuration directive can be used to modify the behaviour. +</p> +? }) + +<? +$ctx->{directive}->( + name => "proxy.proxy-protocol", + levels => [ qw(global host path extension) ], + since => "2.1", + see_also => render_mt(<<'EOT'), +<a href="configure/proxy_directives.html#proxy.timeout.keepalive"><code>proxy.timeout.keepalive</code></a> +EOT + default => q{proxy.proxy-protocol: OFF}, + desc => q{A boolean flag (<code>ON</code> or <code>OFF</code>) indicating if <a href="http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt" target="_blank">PROXY protocol</a> should be used when connecting to the application server.}, +)->(sub { +?> +<p> +When using the PROXY protocol, connections to the application server cannot be persistent (i.e. <a href="configure/proxy_directives.html#proxy.timeout.keepalive"><code>proxy.timeout.keepalive</code></a> must be set to zero). +</p> +? }) + +<? +$ctx->{directive}->( + name => "proxy.emit-x-forwarded-headers", + levels => [ qw(global) ], + since => "2.1", + default => q{proxy.emit-x-forwarded-headers: ON}, + desc => "A boolean flag(<code>ON</code> or <code>OFF</code>) indicating if the server will append or add the <code>x-forwarded-proto</code> and <code>x-forwarded-for</code> request headers.", + see_also => render_mt(<<'EOT'), +<a href="configure/proxy_directives.html#proxy.emit-via-header"><code>proxy.emit-via-header</code></a> +EOT +)->(sub { +?> +<p> +By default, when forwarding an HTTP request H2O sends its own <code>x-forwarded-proto</code> and <code>x-forwarded-for</code> request headers (or might append its value in the <code>x-forwarded-proto</code> case, see <code>proxy.preserve-x-forwarded-proto</code>). This might not be always desirable. Please keep in mind security implications when setting this of <code>OFF</code>, since it might allow an attacker to spoof the originator or the protocol of a request. +</p> +? }) + +<? +$ctx->{directive}->( + name => "proxy.emit-via-header", + levels => [ qw(global) ], + since => "2.2", + default => q{proxy.emit-via-header: ON}, + desc => "A boolean flag (<code>ON</code> or <code>OFF</code>) indicating if the server adds or appends an entry to the <code>via</code> request header.", + see_also => render_mt(<<'EOT'), +<a href="configure/proxy_directives.html#proxy.emit-x-forwarded-headers"><code>proxy.emit-x-forwarded-headers</code></a> +EOT +)->(sub {}) +?> + +<? +for my $action (qw(add append merge set setifempty unset)) { + $ctx->{directive}->( + name => "proxy.header.$action", + levels => [ qw(global host path extensions) ], + since => "2.2", + desc => "Modifies the request headers sent to the application server.", + )->(sub { +?> +<p> +The behavior is identical to <a href="configure/headers_directives.html#header.<?= $action ?>"><code>header.<?= $action ?></code></a> except for the fact that it affects the request sent to the application server. +Please refer to the documentation of the <a href="configure/headers_directives.html">headers handler</a> to see how the directives can be used to mangle the headers. +</p> +<? + }); +} +?> + +<? +$ctx->{directive}->( + name => "proxy.ssl.cafile", + levels => [ qw(global host path extension) ], + since => "2.0", + desc => "Specifies the file storing the list of trusted root certificates.", + see_also => render_mt(<<'EOT'), +<a href="configure/proxy_directives.html#proxy.ssl.verify-peer"><code>proxy.ssl.verify-peer</code></a> +EOT +)->(sub { +?> +<p> +By default, H2O uses <code>share/h2o/ca-bundle.crt</code>. The file contains a set of trusted root certificates maintained by Mozilla, downloaded and converted using <a href="https://curl.haxx.se/docs/mk-ca-bundle.html">mk-ca-bundle.pl</a>. +</p> +? }) + +<? +$ctx->{directive}->( + name => "proxy.ssl.session-cache", + levels => [ qw(global host path extension) ], + since => "2.1", + default => "proxy.ssl.session-cache: ON", + desc => "Specifies whether if and how a session cache should be used for TLS connections to the application server.", +)->(sub { +?> +<p> +Since version 2.1, result of the TLS handshakes to the application server is memoized and later used to resume the connection, unless set to <code>OFF</code> using this directive. +If the value is a mapping, then the following two attributes must be specified: +<dl> +<dt>lifetime:</dt> +<dd>validity of session cache entries in seconds</dd> +<dt>capacity:</dt> +<dd>maxmum number of entries to be kept in the session cache</dd> +</dl> +If set to <code>ON</code>, <code>lifetime</code> and <code>capacity</code> will be set to 86,400 (one day) and 4,096. +</p> +? }) + +<? +$ctx->{directive}->( + name => "proxy.ssl.verify-peer", + levels => [ qw(global host path extension) ], + since => "2.0", + desc => "A boolean flag (<code>ON</code> or <code>OFF</code>) indicating if the server certificate and hostname should be verified.", + default => q{proxy.ssl.verify-peer: ON}, + see_also => render_mt(<<'EOT'), +<a href="configure/proxy_directives.html#proxy.ssl.cafile"><code>proxy.ssl.cafile</code></a> +EOT +)->(sub { +?> +<p> +If set to <code>ON</code>, the HTTP client implementation of H2O verifies the peer's certificate using the list of trusted certificates as well as compares the hostname presented in the certificate against the connecting hostname. +</p> +? }) + +<? +$ctx->{directive}->( + name => "proxy.timeout.io", + levels => [ qw(global host path extension) ], + default => q{proxy.timeout.io: 30000}, + desc => q{Sets the upstream I/O timeout in milliseconds.}, +)->(sub {}); +?> + +<? +$ctx->{directive}->( + name => "proxy.timeout.keepalive", + levels => [ qw(global host path extension) ], + default => q{proxy.timeout.keepalive: 2000}, + desc => 'Sets the upstream timeout for idle connections in milliseconds.', +)->(sub { +?> +<p> +Upstream connection becomes non-persistent if the value is set to zero. +The value should be set to something smaller than that being set at the upstream server. +</p> +? }) + +<? +$ctx->{directive}->( + name => "proxy.websocket", + levels => [ qw(global host path extension) ], + default => q{proxy.websocket: OFF}, + desc => q{A boolean flag (<code>ON</code> or <code>OFF</code>) indicating whether or not to allow upgrading the proxied connection to <a href="https://tools.ietf.org/html/rfc6455">the WebSocket protocol</a>.}, +)->(sub { +?> +<p> +When set to <code>ON</code>, the proxied connection will be upgraded to a bi-directional tunnel stream if upgrading to WebSocket connection is permitted by the backend server (i.e. if the backend server responds to a WebSocket handshake with <code>101</code> status code). +</p> +<p> +Support for WebSocket is considered experimental for the time being and therefore is not yet turned on by default. +</p> +? }) + +<? +$ctx->{directive}->( + name => "proxy.websocket.timeout", + levels => [ qw(global host path extension) ], + default => q{proxy.websocket.timeout: 300000}, + desc => q{Sets idle timeout of a WebSocket connection being proxied.}, +)->(sub {}) +?> + +? }) diff --git a/web/server/h2o/libh2o/srcdoc/configure/quick_start.mt b/web/server/h2o/libh2o/srcdoc/configure/quick_start.mt new file mode 100644 index 00000000..3ce08697 --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/configure/quick_start.mt @@ -0,0 +1,66 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Configure", "Quick Start")->(sub { + +<p> +In order to run the H2O standalone HTTP server, you need to write a configuration file. +The minimal configuration file looks like as follows. +</p> + +<?= $ctx->{code}->(<< 'EOT') +listen: + port: 8080 +user: nobody +hosts: + "myhost.example.com": + paths: + /: + file.dir: /path/to/the/public-files +access-log: /path/to/the/access-log +error-log: /path/to/the/error-log +pid-file: /path/to/the/pid-file +EOT +?> + +<p> +The configuration instructs the server to: +<ol> +<li>listen to port 8080</li> +<li>under the privileges of <code>nobody</code></li> +<li>serve files under <code>/path/to/the/public-files</code></li> +<li>emit access logs to file: <code>/path/to/the/access-log</code></li> +<li>emit error logs to <code>/path/to/the/error-log</code></li> +<li>store the process id of the server in <code>/path/to/the/pid-file</code> +</ol> +</p> + +<p> +Enter the command below to start the server. +</p> + +<?= $ctx->{code}->(<< 'EOT') +% sudo h2o -m daemon -c /path/to/the/configuration-file +EOT +?> + +<p> +The command instructs the server to read the configuration file, and start in <code>daemon</code> mode, which dispatches a pair of master and worker processes that serves the HTTP requests. +</p> + +<p> +To stop the server, send <code>SIGTERM</code> to the server. +</p> + +<?= $ctx->{code}->(<< 'EOT') +% sudo kill -TERM `cat /path/to/the/pid-file` +EOT +?> + +<h3>Next Step</h3> + +<p> +Now that you know how to start and stop the server, the next step is to learn the <a href="configure.html">configuration directives and their structure</a>, or see <a href="https://github.com/h2o/h2o/wiki#configuration-examples">the configuration examples</a>. +</p> + +</p> + +? }) diff --git a/web/server/h2o/libh2o/srcdoc/configure/redirect_directives.mt b/web/server/h2o/libh2o/srcdoc/configure/redirect_directives.mt new file mode 100644 index 00000000..8fbdd957 --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/configure/redirect_directives.mt @@ -0,0 +1,47 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Configure", "Redirect Directives")->(sub { + +<p> +This document describes the configuration directives of the redirect handler. +</p> + +<? +$ctx->{directive}->( + name => "redirect", + levels => [ qw(path) ], + desc => q{Redirects the requests to given URL.}, +)->(sub { +?> +<p> +The directive rewrites the URL by replacing the host and path part of the URL at which the directive is used with the given URL. For example, when using the configuration below, requests to <code>http://example.com/abc.html</code> will be redirected to <code>https://example.com/abc.html</code>. +</p> +<p> +If the argument is a scalar, the value is considered as the URL to where the requests should be redirected. +</p> +<p> +Following properties are recognized if the argument is a mapping. +<dl> +<dt><code>url</code> +<dd>URL to redirect to +<dt><code>status</code> +<dd>the three-digit status code to use (e.g. <code>301</code>) +<dt><code>internal</code> +<dd>either <code>YES</code> or <code>NO</code> (default); if set to <code>YES</code>, then the server performs an internal redirect and return the content at the redirected URL +</dl> +</p> +<?= $ctx->{example}->('Redirect all HTTP to HTTPS permanently (except for the files under <code>RSS</code>)', <<'EOT'); +hosts: + "example.com:80": + paths: + "/": + redirect: + status: 301 + url: "https://example.com/" + "/rss": + file.dir: /path/to/rss +EOT +?> + +? }) + +? }) diff --git a/web/server/h2o/libh2o/srcdoc/configure/reproxy_directives.mt b/web/server/h2o/libh2o/srcdoc/configure/reproxy_directives.mt new file mode 100644 index 00000000..3288a65e --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/configure/reproxy_directives.mt @@ -0,0 +1,29 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Configure", "Reproxy Directives")->(sub { + +<p> +This document describes the configuration directives of the reproxy handler. +</p> + +<? +$ctx->{directive}->( + name => "reproxy", + levels => [ qw(global host path extension) ], + default => q{reproxy: OFF}, + desc => <<'EOT', +A boolean flag (<code>ON</code> or <code>OFF</code>) indicating if the server should recognize the <code>X-Reproxy-URL</code> header sent from <a href="configure/proxy_directives.html#proxy.reverse.url">upstream servers</a>. +EOT +)->(sub { +?> +<p> +If H2O recognizes the header, it fetches the contents of the resource specified by the header, and sends the contents as the response to the client. +If the status code associated with the <code>X-Reproxy-URL</code> header is 307 or 308, then the method of the original request is used to obtain the specified resource. +Otherwise, the request method is changed to <code>GET</code>. +</p> +<p> +For example, an upstream server may send an URL pointing to a large image using the <code>X-Reproxy-URL</code> header stored on a distributed file system, and let H2O fetch and return the content to the client, instead of fetching the image by itself. +Doing so would reduce the load on the application server. +</p> +? }) + +? }) diff --git a/web/server/h2o/libh2o/srcdoc/configure/status_directives.mt b/web/server/h2o/libh2o/srcdoc/configure/status_directives.mt new file mode 100644 index 00000000..a78689fb --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/configure/status_directives.mt @@ -0,0 +1,63 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Configure", "Status Directives")->(sub { + +<p> +The status handler exposes the current states of the HTTP server. +This document describes the configuration directives of the handler. +</p> + +<? +$ctx->{directive}->( + name => "status", + levels => [ qw(path) ], + since => '2.0', + desc => <<'EOT', +If the argument is <code>ON</code>, the directive registers the status handler to the current path. +EOT +)->(sub { +?> +<p> +Access to the handler should be <a href="configure/mruby.html#access-control">restricted</a>, considering the fact that the status includes the details of in-flight HTTP requests. +The example below uses <a href="configure/basic_auth.html">Basic authentication</a>. +</p> +<?= $ctx->{example}->("Exposing status with Basic authentication", <<'EOT'); +paths: + /server-status: + mruby.handler: | + require "htpasswd.rb" + Htpasswd.new("/path/to/.htpasswd", "status") + status: ON +EOT +?> +<p> +The information returned by the <code>/json</code> handler can be filtered out using the optional <code>show=module1,module2</code> parameter. +There are currently three modules defined: +<ul> +<li><code>requests</code>: displays the requests currently in-flight.</li> +<li><code>durations</code>: displays durations statistics for requests since server start time in seconds (returns all zeros unless <code>duration-stats</code> is <code>ON</code>).</li> +<li><code>errors</code>: displays counters for internally generated errors.</li> +<li><code>main</code>: displays general daemon-wide stats.</li> +</ul> +</p> +? }) + +<? +$ctx->{directive}->( + name => "duration-stats", + levels => [ qw(global) ], + since => '2.1', + default => 'duration-stats: OFF', + desc => q{Gather timing stats for requests.}, +)->(sub { +?> +</p> +<p> +If the argument is <code>ON</code>, this directive populates duration statistics in seconds, to be consumed by status handlers. +Enabling this feature has a noticeable CPU and memory impact. +</p> +<p> +Note that the time spent while processing a request in a blocking manner (such as opening a file or a mruby handler that does invoke a network operation) will not be reflected to the <code>process_time</code> element of the duration stats due to the fact that the timer being used for measuring the time spent is updated only once per loop. +</p> +? }) + +? }) diff --git a/web/server/h2o/libh2o/srcdoc/configure/syntax_and_structure.mt b/web/server/h2o/libh2o/srcdoc/configure/syntax_and_structure.mt new file mode 100644 index 00000000..f8f8cd4f --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/configure/syntax_and_structure.mt @@ -0,0 +1,216 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Configure", "Syntax and Structure")->(sub { + +<h3>Syntax</h3> + +<p> +H2O uses <a href="http://www.yaml.org/">YAML</a> 1.1 as the syntax of its configuration file. +</p> + +<h3 id="config_levels">Levels of Configuration</h3> + +<p> +When using the configuration directives of H2O, it is important to understand that there are four configuration levels: global, host, path, extension. +</p> + +<p> +Global-level configurations affect the entire server. +Host-level configurations affect the configuration for the specific hostname (i.e. corresponds to the <a href="http://httpd.apache.org/docs/2.4/vhosts/"><VirtualHost></a> directive of the Apache HTTP Server). +Path-level configurations only affect the behavior of resources specific to the path. +</p> + +<p> +Extension-level configuration affect how files with certain extensions are being served. +For example, it is possible to map files with <code>.php</code> extension to the FastCGI handler running the <code>php-cgi</code> command. +</p> + +<p> +Consider the following example. +</p> + +<?= $ctx->{code}->(<< 'EOT') +hosts: + "example.com": + listen: + port: 443 + ssl: + certificate-file: etc/site1.crt + key-file: etc/site1.key + paths: + "/": + file.dir: htdocs/site1 + "/icons": + file.dir: icons + expires: 1 day + "example.com:80": + listen: + port: 80 + paths: + "/": + redirect: "https://example.com/" +EOT +?> + +<p> +In the example, two host-level configurations exist (under the <code>hosts</code> mapping), each of them listening to different ports. +The first host listens to port 443 using TLS (i.e. HTTPS) using the specified server certificate and key. +It has two path-level configurations, one for <code>/</code> and the other for <code>/icons</code>, each of them pointing to different local directories containing the files to be served. +The latter also has the <code>expires</code> directive set, so that <code>Cache-Control: max-age=86400</code><?= $ctx->{note}->("1 day is equivalent to 86400 seconds") ?> header would be sent. +The second host accepts connections on port 80 (via the plain-text HTTP protocol), and redirects all the requests to the first host using HTTPS. +</p> + +<p> +Certain configuration directives can be used in more than one levels. For example, the <a href="configure/base_directives.html#listen"><code>listen</code></a> can be used either at the global level or at the host level. +<a href="configure/expires_directives.html#expires"><code>Expires</code></a> can be used at all levels. +On the other hand <a href="configure/file_directives.html#file.dir"><code>file.dir</code></a> can only be used at the path level. +</p> + +<h3 id="path-level">Path-level configuration</h3> + +<p> +Values of the path-level configuration define the action(s) to be taken when the server processes a request that prefix-matches to the configured paths. +Each entry of the mapping associated to the paths is evaluated in the order they appear. +</p> + +<p> +Consider the following example. +When receiving a request for <code>https://example.com/foo</code>, <a href="configure/file_directives.html">the file handler</a> is first executed trying to serve a file named <code>/path/to/doc-root/foo</code> as the response. +In case the file does not exist, then <a href="configure/fastcgi_directives.html">the FastCGI handler</a> is invoked. +</p> + +<?= $ctx->{code}->(<< 'EOT') +hosts: + "example.com": + listen: + port: 443 + ssl: + certificate-file: etc/site1.crt + key-file: etc/site1.key + paths: + "/": + file.dir: /path/to/doc-root + fastcgi.connect: + port: /path/to/fcgi.sock + type: unix +EOT +?> + +<p> +Starting from version 2.1, it is also possible to define the path-level configuration as a sequence of mappings instead of a single mapping. +The following example is identical to the previous one. +Notice the dashes placed before the handler directives. +</p> + +<?= $ctx->{code}->(<< 'EOT') +hosts: + "example.com": + listen: + port: 443 + ssl: + certificate-file: etc/site1.crt + key-file: etc/site1.key + paths: + "/": + - file.dir: /path/to/doc-root + - fastcgi.connect: + port: /path/to/fcgi.sock + type: unix +EOT +?> + +<h3 id="yaml_alias">Using YAML Alias</h3> + +<p> +H2O resolves <a href="http://yaml.org/YAML_for_ruby.html#aliases_and_anchors">YAML aliases</a> before processing the configuration file. +Therefore, it is possible to use an alias to reduce the redundancy of the configuration file. +For example, the following configuration reuses the first <code>paths</code> element (that is given an anchor named <code>default_paths</code>) in the following definitions. + +<?= $ctx->{code}->(<< 'EOT') +hosts: + "example.com": + listen: + port: 443 + ssl: + certificate-file: /path/to/example.com.crt + key-file: /path/to/example.com.crt + paths: &default_paths + "/": + file.dir: /path/to/doc-root + "example.org": + listen: + port: 443 + ssl: + certificate-file: /path/to/example.org.crt + key-file: /path/to/example.org.crt + paths: *default_paths +EOT +?> + +<h3 id="yaml_merge">Using YAML Merge</h3> + +<p> +Since version 2.0, H2O recognizes <a href="http://yaml.org/type/merge.html">Merge Key Language-Independent Type for YAML™ Version 1.1</a>. +Users can use the feature to merge an existing mapping against another. +The following example reuses the TLS configuration of <code>example.com</code> in <code>example.org</code>. +</p> + +<?= $ctx->{code}->(<< 'EOT') +hosts: + "example.com": + listen: + port: 443 + ssl: &default_ssl + minimum-version: TLSv1.2 + cipher-suite: ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256 + certificate-file: /path/to/example.com.crt + key-file: /path/to/example.com.crt + paths: + ... + "example.org": + listen: + port: 443 + ssl: + <<: *default_ssl + certificate-file: /path/to/example.org.crt + key-file: /path/to/example.org.crt + paths: + ... +EOT +?> + +<h3 id="including_files">Including Files</h3> + +<p> +Starting from version 2.1, it is possible to include a YAML file from the configuration file using <code>!file</code> custom YAML tag. +The following example extracts the TLS configuration into <code>default_ssl.conf</code> and include it multiple times in <code>h2o.conf</code>. +</p> + +<?= $ctx->{example}->('default_ssl.conf', << 'EOT') +minimum-version: TLSv1.2 +cipher-suite: ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256 +certificate-file: /path/to/example.com.crt +key-file: /path/to/example.com.crt +EOT +?> + +<?= $ctx->{example}->('h2o.conf', << 'EOT') +hosts: + "example.com": + listen: + port: 443 + ssl: !file default_ssl.conf + paths: + ... + "example.org": + listen: + port: 443 + ssl: + <<: !file default_ssl.conf + certificate-file: /path/to/example.org.crt + key-file: /path/to/example.org.crt + paths: + ... +EOT +?> + +? }) diff --git a/web/server/h2o/libh2o/srcdoc/configure/throttle_response_directives.mt b/web/server/h2o/libh2o/srcdoc/configure/throttle_response_directives.mt new file mode 100644 index 00000000..415c8afa --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/configure/throttle_response_directives.mt @@ -0,0 +1,44 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Configure", "Throttle Response Directives")->(sub { + +<p> +The throttle response handler performs per response traffic throttling, when an <code>X-Traffic</code> header exists in the response headers. +</p> +<p> +The value of <code>X-Traffic</code> header should be an integer that represents the speed you want in bytes per second. This header CAN be set with <a href="configure/headers_directives.html#header.add"><code>header.add</code></a> so that traffic for static assets can also be easily throttled. +</p> +<p> +The following are the configuration directives recognized by the handler. +</p> + +<? +$ctx->{directive}->( + name => "throttle-response", + levels => [ qw(global host path extension) ], + default => "throttle-response: OFF", + since => '2.1', + desc => <<'EOT', +Enables traffic throttle per HTTP response. +EOT +)->(sub { +?> +<p> +If the argument is <code>ON</code>, the traffic per response is throttled as long as a legal <code>X-Traffic</code> header exists. +If the argument is <code>OFF</code>, traffic throttle per response is disabled. +</p> +<?= $ctx->{example}->('Enabling traffic throttle per response with static file configuration', <<'EOT') +# enable throttle +throttle-response: ON + +# an example host configuration that throttle traffic to ~100KB/s +hosts: + default: + paths: + /: + file.dir: /path/to/assets + header.add: "X-Traffic: 100000" +EOT +?> +? }) + +? }) diff --git a/web/server/h2o/libh2o/srcdoc/faq.mt b/web/server/h2o/libh2o/srcdoc/faq.mt new file mode 100644 index 00000000..72899e81 --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/faq.mt @@ -0,0 +1,56 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Frequently Asked Questions")->(sub { + +<h3 id="license">What are the license terms?</h3> + +<div> +H2O is licensed under <a href="http://opensource.org/licenses/MIT">the MIT license</a>. +</div> +<div> +Portions of the software use following libraries that are also licensed under the MIT license: <a href="https://github.com/h2o/h2o/blob/master/deps/klib/khash.h">khash.h</a>, <a href="https://github.com/h2o/h2o/blob/master/deps/picohttpparser/">PicoHTTPParser</a>, <a href="https://github.com/h2o/h2o/blob/master/deps/yaml/">libyaml</a>. +</div> + +<div> +Depending on how H2O is configured, the software links against OpenSSL or LibreSSL, both of which are <a href="https://www.openssl.org/source/license.html">dual-licensed under the OpenSSL License and the original SSLeay license</a>. +</div> + +<h3 id="design-docs">Are there any design documents?</h3> + +<div> +Please refer to the main developer's <a href="http://www.slideshare.net/kazuho/h2o-20141103pptx" target="_blank">presentation slides</a> at the HTTP/2 conference, and <a href="http://blog.kazuhooku.com" target="_blank">his weblog</a>. +</div> + +<h3 id="libh2o">How do I use H2O as a library?</h3> + +<div> +<p> +Aside from the standalone server, H2O can also be used as a software library. +The name of the library is <code>libh2o</code>. +</p> +<p> +To build H2O as a library you will need to install the following dependencies: +<ul> +<li><a href="https://github.com/libuv/libuv/">libuv</a> version 1.0 or above</li> +<li><a href="https://www.openssl.org/">OpenSSL</a> version 1.0.2 or above<?= $ctx->{note}->(q{libh2o cannot be linked against the bundled LibreSSL; see <a href="https://github.com/h2o/h2o/issues/290">issue #290</a>}) ?></li> +</ul> +In case the dependencies are installed under a non-standard path, <code>PKG_CONFIG_PATH</code> configuration variable can be used for specifying their paths. For example, the following snippet builds <code>libh2o</code> using the libraries installed in their respective paths. +</p> + +<?= $ctx->{code}->(<< 'EOT') +% PKG_CONFIG_PATH=/usr/local/libuv-1.4/lib/pkgconfig:/usr/local/openssl-1.0.2a/lib/pkgconfig cmake . +% make libh2o +EOT +?> + +<p> +For more information, please refer to the <a href="https://github.com/h2o/h2o/labels/libh2o">GitHub issues tagged as libh2o</a>. +</p> +</div> + +<h3 id="issues">I have a problem. Where should I look for answers?</h3> + +<div> +Please refer to the <a href="https://github.com/h2o/h2o/labels/FAQ">GitHub issues tagged as FAQ</a>. +</div> + +? }) diff --git a/web/server/h2o/libh2o/srcdoc/index.mt b/web/server/h2o/libh2o/srcdoc/index.mt new file mode 100644 index 00000000..1d6f93d9 --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/index.mt @@ -0,0 +1,45 @@ +? my $note = $main::context->{note}; +? $_mt->wrapper_file("wrapper.mt")->(sub { + +<div style="margin-top: 3em;"> +<p> +H2O is a new generation HTTP server that <b>provides quicker response to users with less CPU utilization</b> when compared to older generation of web servers. +Designed from ground-up, the server takes full advantage of <a href="https://tools.ietf.org/html/rfc7540">HTTP/2</a> features including <a href="configure/http2_directives.html#prioritization">prioritized content serving</a> and <a href="configure/http2_directives.html#server-push">server push</a>, promising outstanding experience to the visitors of your web site. +<div align="center"> +<a href="assets/8mbps100msec-nginx195-h2o150.png" target="_blank"><img src="assets/8mbps100msec-nginx195-h2o150.png" width="333" height="250"></a> +<a href="assets/staticfile612-nginx1910-h2o170.png" target="_blank"><img src="assets/staticfile612-nginx1910-h2o170.png" width="200" height="250"></a> +</div> +Explanation of the benchmark charts can be found in the <a href="benchmarks.html">benchmarks</a> page. +<p> + +</p> +</div> + +<h3>Key Features</h3> + +<ul> +<li>HTTP/1.0, HTTP/1.1 +<li><a href="configure/http2_directives.html">HTTP/2</a> +<ul> +<li>full support for dependency and weight-based prioritization with <a href="configure/http2_directives.html#http2-reprioritize-blocking-assets">server-side tweaks</a></li> +<li><a href="configure/http2_directives.html#http2-casper">cache-aware server push</a></li> +</ul> +</li> +<li>TCP Fast Open +<li><a href="configure/base_directives.html#listen-ssl">TLS</a> +<ul> +<li>session resumption (standalone & memcached) +<li>session tickets with automatic key rollover +<li>automatic OCSP stapling +<li>forward secrecy & fast AEAD ciphers<?= $note->(q{chacha20-poly1305: see <a href="https://blog.cloudflare.com/do-the-chacha-better-mobile-performance-with-cryptography/">Do the ChaCha: better mobile performance with cryptography</a>}) ?></li> +<li><a href="configure/base_directives.html#neverbleed">private key protection using privilege separation</a> +</ul> +</li> +<li><a href="configure/file_directives.html">static file serving</a> +<li><a href="configure/fastcgi_directives.html">FastCGI</a> +<li><a href="configure/proxy_directives.html">reverse proxy</a> +<li><a href="configure/mruby.html">scriptable using mruby</a> (Rack-based) +<li>graceful restart and self-upgrade +</ul> + +? }) diff --git a/web/server/h2o/libh2o/srcdoc/install.mt b/web/server/h2o/libh2o/srcdoc/install.mt new file mode 100644 index 00000000..e2a37134 --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/install.mt @@ -0,0 +1,121 @@ +? my $ctx = $main::context; +? $_mt->wrapper_file("wrapper.mt", "Install")->(sub { + +<h3 id="binary">Installing a Binary Package</h3> + +<p> +Thanks to others, H2O is provided as a binary package on some environments. +Therefore you may try to at first install the software using your favorite packaging system, and then resort to installing from source as described below. +</p> + +<p> +At the time being, following packages are known to be actively maintained<?= $ctx->{note}->(q{Please open a new issue on <a href="https://github.com/h2o/h2o">Github</a> if you want a new package to get added.}) ?>: +<ul> +<li><a href="http://portsmon.freebsd.org/portoverview.py?category=www&portname=h2o">FreeBSD</a></li> +<li><a href="http://brewformulas.org/H2o">Homebrew (OS X)</a></li> +<li><a href="https://github.com/tatsushid/h2o-rpm">RPM (Fedora, RHEL/CentOS, OpenSUSE)</a></li> +<li><a href="https://hub.docker.com/r/lkwg82/h2o-http2-server/">Docker Image</a></li> +</ul> +</p> + +<h3 id="from-source">Installing from Source</h3> + +<p> +Download a release version from <a href="https://github.com/h2o/h2o/releases">the releases page</a> or clone the master branch from <a href="https://github.com/h2o/h2o/">the source repository</a>, and build it using <a href="http://www.cmake.org/">CMake</a><?= $ctx->{note}->("CMake is a popular build tool that can be found as a binary package on most operating systems.") ?>. +</p> + +<?= $ctx->{code}->(<< 'EOT') +% cmake -DWITH_BUNDLED_SSL=on . +% make +% sudo make install +EOT +?> + +<p> +When complete, H2O will be installed under <code>/usr/local</code>. +</p> + +<p> +Start the installed server using the example configuration to confirm that it actually works (note: without the use of <code>-m</code> option the server runs as a foreground process; press <code>Ctrl-C</code> to stop). +</p> + +<?= $ctx->{code}->(<< 'EOT') +% /usr/local/bin/h2o -c examples/h2o/h2o.conf +EOT +?> + +<p> +The example configuration starts a server that listens to port 8080 (HTTP) and port 8081 (HTTPS). Try to access the ports using the protocols respectively (note: when accessing via HTTPS it is likely that you would see hostname mismatch errors reported by the web browsers). +</p> + +<p> +When complete, proceed to <a href="configure.html">Configure</a> section for how to setup the server. +</p> + +<h4>CMake Options</h4> + +<p> +Following list shows the interesting arguments recognized by CMake. + +<dl> +<dt><code>-DCMAKE_INSTALL_PREFIX=<i>directory</i></code></dt> +<dd> +This option specifies the directory to which H2O will be installed (default: <code>/usr/local</code>). +</dd> +<dt><code>-DWITH_BUNDLED_SSL=<i>on</i>|<i>off</i></code></dt> +<dd> +This option instructs whether or not to use <a href="http://www.libressl.org/">LibreSSL</a> being bundled (default: <code>off</code> if <a href="https://www.openssl.org/">OpenSSL</a> version >= 1.0.2 is found, <code>on</code> if otherwise). Read the section below for comparison between OpenSSL and LibreSSL. +</dd> +<dt><code>-DWITH_MRUBY=<i>on</i>|<i>off</i></code></dt> +<dd> +This option instructs whether or not to build the standalone server with support for <a href="configure/mruby.html">scripting using mruby</a>. +It is turned on by default if the prerequisites (<a href="https://www.gnu.org/software/bison/">bison</a>, <a href="https://www.ruby-lang.org/">ruby</a> and the development files<?= $ctx->{note}->(q{<code>mkmf</code> - a program for building ruby extensions is required. In many distributions, the program is packaged as part of <code>ruby-dev<code> or <code>ruby-devel</code> package.}) ?>) are found. +</dl> +</p> + +<h3>Installing from Source, using OpenSSL</h3> + +<p> +Generally speaking, we believe that using LibreSSL is a better choice for running H2O, since LibreSSL not only is considered to be more secure than OpenSSL but also provides support for new ciphersuites such as <code>chacha20-poly1305</code> which is the preferred method of Google Chrome<?= $ctx->{note}->(q{ref: <a href="https://blog.cloudflare.com/do-the-chacha-better-mobile-performance-with-cryptography/">Do the ChaCha: better mobile performance with cryptography</a>}) ?>. However, it is also true that LibreSSL is slower than OpenSSL on some benchmarks. So if you are interested in benchmark numbers, using OpenSSL is a reasonable choice. +</p> + +<p> +The difficulty in using OpenSSL is that the HTTP/2 specification requires the use of an extension to the TLS protocol named ALPN, which has only been supported since OpenSSL 1.0.2<?= $ctx->{note}->("It is possible to build H2O using prior versions of OpenSSL, but some (if not all) web browsers are known for not using HTTP/2 when connecting to servers configured as such.") ?>. Therefore it is highly likely that you would need to manually install or upgrade OpenSSL on your system. +</p> + +<p> +Once you have installed OpenSSL 1.0.2, it is possible to build H2O that links against the library. As an safeguard it is advised to use <code>-DWITH_BUNDLED_SSL</code> set to <code>off</code>, so that the server would not accidentally link against the bundled LibreSSL. +CMake will search for OpenSSL by looking at the default search paths. +</p> + +<?= $ctx->{code}->(<< 'EOT') +% cmake -DWITH_BUNDLED_SSL=off +% make +% sudo make install +EOT +?> + +<p> +Two ways exist to specify the directory in which CMake should search for OpenSSL. +The preferred approach is to use the <code>PKG_CONFIG_PATH</code> environment variable. +</p> + +<?= $ctx->{code}->(<< 'EOT') +% PKG_CONFIG_PATH=/usr/local/openssl-1.0.2/lib/pkgconfig cmake -DWITH_BUNDLED_SSL=off +% make +% sudo make install +EOT +?> + +<p> +In case your OpenSSL installation does not have the <code>lib/pkgconfig</code> directory, you may use <code>OPENSSL_ROOT_DIR</code> environment variable to specify the root directory of the OpenSSL being installed. However, it is likely that CMake version 3.1.2 or above is be required when using this approach<?= $ctx->{note}->(q{ref: <a href="https://github.com/h2o/h2o/issues/277">h2o issue #277</a>, <a href="http://public.kitware.com/Bug/view.php?id=15386">CMake issue 0015386</a>}) ?>. +</p> + +<?= $ctx->{code}->(<< 'EOT') +% OPENSSL_ROOT_DIR=/usr/local/openssl-1.0.2 cmake -DWITH_BUNDLED_SSL=off +% make +% sudo make install +EOT +?> + +? }) diff --git a/web/server/h2o/libh2o/srcdoc/snippets/directive.mt b/web/server/h2o/libh2o/srcdoc/snippets/directive.mt new file mode 100644 index 00000000..4b880f31 --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/snippets/directive.mt @@ -0,0 +1,28 @@ +? my $ctx = $main::context; +? my ($content, $args) = @_; +<div id="<?= $args->{name} ?>" class="directive-head"> +? if ($args->{since}) { +<div class="directive-since">since v<?= $args->{since} ?></div> +? } +<h3><a href="<?= $ctx->{filename} ?>#<?= $args->{name} ?>"><code>"<?= $args->{name} ?>"</code></a></h3> +</div> + +<dl class="directive-desc"> +<dt>Description:</dt> +<dd> +<p> +<?= Text::MicroTemplate::encoded_string($args->{desc}) ?> +</p> +<?= $content ?> +</dd> +<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt> +<dd><?= join(", ", @{$args->{levels}}) ?></dd> +? if ($args->{default}) { +<dt>Default:</dt> +<dd><code><pre><?= $args->{default} ?></pre></code> +? } +? if ($args->{see_also}) { +<dt>See also:</dt> +<dd><?= $args->{see_also} ?></dd> +? } +</dl> diff --git a/web/server/h2o/libh2o/srcdoc/snippets/mruby_method.mt b/web/server/h2o/libh2o/srcdoc/snippets/mruby_method.mt new file mode 100644 index 00000000..c5005899 --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/snippets/mruby_method.mt @@ -0,0 +1,33 @@ +? my $ctx = $main::context; +? my ($content, $args) = @_; +<div id="<?= $args->{name} ?>" class="mruby-method-head"> +? if ($args->{since}) { +<div class="mruby-method-since">since v<?= $args->{since} ?></div> +? } +<h3><a href="<?= $ctx->{filename} ?>#<?= $args->{name} ?>"><code>"<?= $args->{name} ?>"</code></a></h3> +</div> + +<dl class="mruby-method-desc"> +<dt>Description:</dt> +<dd> +<p> +<?= Text::MicroTemplate::encoded_string($args->{desc}) ?> +</p> +<?= $content ?> +</dd> +? if (@{$args->{params} || []}) { +<dt>Parameters:</dt> +<dd> +<dl class="mruby-method-parameters"> +? for my $param (@{ $args->{params} }) { + <dt><?= $param->{label} ?></dt> + <dd><?= $param->{desc} ?></dd> +? } +</dl> +</dd> +? } +? if ($args->{see_also}) { +<dt>See also:</dt> +<dd><?= $args->{see_also} ?></dd> +? } +</dl> diff --git a/web/server/h2o/libh2o/srcdoc/snippets/wrapper.mt b/web/server/h2o/libh2o/srcdoc/snippets/wrapper.mt new file mode 100644 index 00000000..86f551d5 --- /dev/null +++ b/web/server/h2o/libh2o/srcdoc/snippets/wrapper.mt @@ -0,0 +1,108 @@ +<? + +my ($content, @title) = @_; +my $ctx = $main::context; +my $create_tab = sub { + my ($fn, $tab_topic) = @_; + my $html; + my $cur_topic = $title[0] || 'Top'; + $cur_topic = "FAQ" + if $cur_topic eq 'Frequently Asked Questions'; + if ($cur_topic eq $tab_topic) { + $html = qq{<td class="selected">@{[Text::MicroTemplate::escape_html($tab_topic)]}</td>}; + } else { + $html = qq{<td><a href="@{[Text::MicroTemplate::escape_html($fn)]}">@{[Text::MicroTemplate::escape_html($tab_topic)]}</a></td>}; + } + Text::MicroTemplate::encoded_string($html); +}; + +?><!DOCTYPE html> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> +<meta name="viewport" content="width=device-width,initial-scale=1,user-scalable=no" /> +? my $base = "../" x (scalar(split '/', $main::context->{filename}) - 1); +? if ($base ne '') { +<base href="<?= $base ?>" /> +? } + +<!-- oktavia --> +<link rel="stylesheet" href="assets/searchstyle.css" type="text/css" /> +<script src="search/jquery-1.9.1.min.js"></script> +<script src="search/oktavia-jquery-ui.js"></script> +<script src="search/oktavia-english-search.js"></script> +<!-- /oktavia --> + +<link rel="stylesheet" href="assets/style.css" type="text/css" /> + +<title><?= join " - ", ($ctx->{filename} ne 'index.html' ? reverse @title : ()), "H2O - the optimized HTTP/2 server" ?></title> +</head> +<body> +<div id="body"> +<div id="top"> + +<h1> +<a href="index.html">H2O</a> +</h1> +<p class="description">the optimized HTTP/1.x, HTTP/2 server</p> + +<!-- oktavia --> +<form id="searchform"> +<input class="search" type="search" name="search" id="search" results="5" value="" placeholder="Search" /> +<div id="searchresult_box"> +<div id="close_search_box">×</div> +<div id="searchresult_summary"></div> +<div id="searchresult"></div> +<div id="searchresult_nav"></div> +<span class="pr">Powered by <a href="https://github.com/shibukawa/oktavia">Oktavia</a></span> +</div> +</form> +<!-- /oktavia --> + +</div> + +<table id="menu"> +<tr> +<?= $create_tab->("index.html", "Top") ?> +<?= $create_tab->("install.html", "Install") ?> +<?= $create_tab->("configure.html", "Configure") ?> +<?= $create_tab->("faq.html", "FAQ") ?> +<td><a href="http://blog.kazuhooku.com/search/label/H2O" target="_blank">Blog</a></td> +<td><a href="http://github.com/h2o/h2o/" target="_blank">Source</a></td> +</tr> +</table> + +<div id="main"> + +? if (@title) { +<h2> +? if (@title > 1) { +? for (my $i = 0; $i < @title - 1; $i++) { +<a href="<?= lc $title[$i] ?>.html"><?= $title[$i] ?></a> > +? } +? } +<?= $title[-1] ?> +</h2> +? } + +?= $content + +? if (my @notes = @{$ctx->{notes}}) { +<div class="notes"> +<h3>Notes:</h3> +<ol> +? for (my $index = 0; $index < @notes; ++$index) { +<li id="note_<?= $index + 1 ?>"><?= $notes[$index] ?></li> +? } +</ol> +</div> +? } + +</div> +<div id="footer"> +<p> +Copyright © 2015 <a href="http://dena.com/intl/">DeNA Co., Ltd.</a> et al. +</p> +</div> +</body> +</html> |