kawipiko/sources/cmd/server/manual.txt

KAWIPIKO-SERVER(1)                 kawipiko                 KAWIPIKO-SERVER(1)



NAME
       kawipiko -- blazingly fast static HTTP server - kawipiko-server

          >> kawipiko-server --help
          >> kawipiko-server --man

          --archive <path>
          --archive-inmem           (memory-loaded archive file)
          --archive-mmap            (memory-mapped archive file)
          --archive-preload         (preload archive in OS cache)

          --bind <ip>:<port>        (HTTP, only HTTP/1.1, FastHTTP)
          --bind-2 <ip>:<port>      (HTTP, only HTTP/1.1, Go net/http)
          --bind-tls <ip>:<port>    (HTTPS, only HTTP/1.1, FastHTTP)
          --bind-tls-2 <ip>:<port>  (HTTPS, with HTTP/2, Go net/http)
          --bind-quic <ip>:<port>   (HTTPS, with HTTP/3)

          --http1-disable
          --http2-disable
          --http3-alt-svc <ip>:<port>

          --tls-bundle <path>       (TLS certificate bundle)
          --tls-public <path>       (TLS certificate public)
          --tls-private <path>      (TLS certificate private)
          --tls-self-rsa            (use self-signed RSA)
          --tls-self-ed25519        (use self-signed Ed25519)

          --processes <count>       (of slave processes)
          --threads <count>         (of threads per process)
          --index-all
          --index-paths
          --index-data-meta
          --index-data-content

          --hosts-disable           (ignore `Host` header)

          --special-pages-disable
          --security-headers-disable
          --security-headers-tls

          --limit-memory <MiB>
          --timeout-disable

          --report  --quiet  --debug

          --help       (show this short help)
          --man        (show the full manual)

          --dummy
          --dummy-empty
          --dummy-delay <duration>

          --profile-cpu <path>
          --profile-mem <path>


                                        ----




FLAGS
       --bind <ip:port>, --bind-tls <ip:port>, --bind-2 <ip:port>,
       --bind-tls-2 <ip:port>, and --bind-quic <ip:port>
          The IP and port to listen for requests with:

          • (insecure) HTTP/1.1 for --bind, leveraging fasthttp library;

          • (secure) HTTP/1.1 over TLS for --bind-tls, leveraging fasthttp
            library;

          • (insecure) HTTP/1.1 for --bind-2`, leveraging Go's net/http
            library; (not as performant as the fasthttp powered endpoint;)

          • (secure) H2 or HTTP/1.1 over TLS for --bind-tls-2, leveraging Go's
            net/http;  (not as performant as the fasthttp powered endpoint;)

          • (secure) H3 over QUIC for --bind-quic, leveraging
            github.com/lucas-clemente/quic-go library;  (given that H3 is
            still a new protocol, this must be used with caution;  also one
            should use the --http3-alt-svc <ip:port>;)

          • if one uses just --bind-tls (without --bind-tls-2, and without
            --http2-disabled), then the TLS endpoint is split between fasthttp
            for HTTP/1.1 and Go's net/http for H2;

       --tls-bundle <path>, --tls-public <path>, and --tls-private <path>
       (optional)
          If TLS is enabled, these options allows one to specify the
          certificate to use, either as a single file (a bundle) or separate
          files (the actual public certificate and the private key).

          If one doesn't specify any of these options, an embedded self-signed
          certificate will be used.  In such case, one can choose between RSA
          (the --tls-self-rsa flag) or Ed25519 (the --tls-self-ed25519 flag);

       --http1-disable, --http2-disable
          Disables that particular protocol.  (It can be used only with
          --bind-tls-2, given that fasthttp only supports HTTP/1.)

       --processes <count> and --threads <count>
          The number of processes and threads per each process to start.
          (Given Go's concurrency model, the threads count is somewhat a soft
          limit, hinting to the runtime the desired parallelism level.)

          It is highly recommended to use one process and as many threads as
          there are cores.

          Depending on the use-case, one can use multiple processes each with
          a single thread;  this would reduce goroutine contention if it
          causes problems.  (However note that if using --archive-inmem, then
          each process will allocate its own copy of the database in RAM;  in
          such cases it is highly recommended to use --archive-mmap.)

       --archive <path>
          The path of the CDB file that contains the archived static content.
          (It can be created with the kawipiko-archiver tool.)

       --archive-inmem
          Reads the CDB file in RAM, and thus all requests are served from RAM
          without touching the file-system.  (The memory impact is equal to
          the size of the CDB archive.  This can be used if enough RAM is
          available to avoid swapping.)

       --archive-mmap
          (recommended) The CDB file is memory mapped, thus reading its data
          uses the kernel's file-system cache, as opposed to issuing read
          syscalls.

       --archive-preload
          Before starting to serve requests, read the CDB file so that its
          data is buffered in the kernel's file-system cache.  (This option
          can be used with or without --archive-mmap.)

       --index-all, --index-paths, --index-data-meta,  and
       --index-data-content
          In order to serve a request kawipiko does the following:

          • given the request's path, it is used to locate the corresponding
            resource's metadata (i.e. response headers) and data (i.e.
            response body) references; by using --index-paths a RAM-based
            lookup table is created to eliminate a CDB read operation for this
            purpose;  (the memory impact is proportional to the size of all
            resource paths combined;  given that the number of resources is
            acceptable, say up to a couple hundred thousand, one could safely
            use this option;)

          • based on the resource's metadata reference, the actual metadata
            (i.e. the response headers) is located; by using --index-data-meta
            a RAM-based lookup table is created to eliminate a CDB read
            operation for this purpose;  (the memory impact is proportional to
            the size of all resource metadata blocks combined;  given that the
            metadata blocks are deduplicated, one could safely use this
            option;  if one also uses --archive-mmap or --archive-inmem, then
            the memory impact is only proportional to the number of resource
            metadata blocks;)

          • based on the resource's data reference, the actual data (i.e. the
            response body) is located; by using --index-data-content a
            RAM-based lookup table is created to eliminate a CDB operation
            operation for this purpose;  (the memory impact is proportional to
            the size of all resource data blocks combined;  one can use this
            option to obtain the best performance;  if one also uses
            --archive-mmap or --archive-inmem, then the memory impact is only
            proportional to the number of resource data blocks;)

          • --index-all enables all the options above;

          • (depending on the use-case) it is recommended to use
            --index-paths;  if --exclude-etag was used during archival, one
            can also use --index-data-meta;

          • it is recommended to use either --archive-mmap or
            --archive-inmem, else (especially if data is indexed) the
            resulting effect is that of loading everything in RAM;

       --hosts-disable
          Disables the virtual-hosts feature by ignoring the Host header.

       --special-pages-disable
          Disables serving a few special pages internal to the server like:
             /__/about /__/version /__/heartbeat /__/sources.md5
             /__/sources.cpio /__/banners/errors/403 /__/banners/errors/...

       --security-headers-disable
          Disables adding a few security related headers:

             Referrer-Policy: strict-origin-when-cross-origin
             X-Content-Type-Options: nosniff
             X-XSS-Protection: 1; mode=block
             X-Frame-Options: sameorigin

       --security-headers-tls
          Enables adding the following TLS related headers to the response:

             Strict-Transport-Security: max-age=31536000
             Content-Security-Policy: upgrade-insecure-requests

          These instruct the browser to always use HTTPS for the served
          domain.  (Useful even without HTTPS, when used behind a TLS
          terminator, load-balancer or proxy that do support HTTPS.)

       --report
          Enables periodic reporting of various metrics.  Also enables
          reporting a selection of metrics if certain thresholds are matched
          (which most likely is a sign of high-load).

       --quiet
          Disables most logging messages.

       --debug
          Enables all logging messages.

       --dummy, --dummy-empty
          It starts the server in a "dummy" mode, ignoring all archive related
          arguments and always responding with hello world!\n (unless
          --dummy-empty was used) and without additional headers except the
          HTTP status line and Content-Length.

          This argument can be used to benchmark the raw performance of the
          underlying fasthttp, Go's net/http, or QUIC performance;  this is
          the upper limit of the achievable performance given the underlying
          technologies.  (From my own benchmarks kawipiko's adds only about
          ~15% overhead when actually serving the hello-world.cdb archive.)

       --dummy-delay <duration>
          Enables delaying each response with a certain amount (for example
          1s, 1ms, etc.)

          It can be used to simulate the real-world network latencies, perhaps
          to see how a site with many resources loads in various conditions.
          (For example, see an experiment I made with an image made out of
          1425 tiles.)

       --profile-cpu <path>, and --profile-mem <path>
          Enables CPU and memory profiling using Go's profiling
          infrastructure.



volution.ro                       2022-09-02                KAWIPIKO-SERVER(1)