libs/lucid/docs/OVERVIEW

   1                                         LuCId Network Superserver in Lua
   2
   3 *** Abstract ***
   4 LuCId is a network superserver written in Lua based on the nixio POSIX library.
   5 It supports IPv4, IPv6, TLS, asynchronous and synchronous IO and can be extended
   6 to handle any kind of IO events on file descriptors. LuCId is also able to
   7 generate RSA private keys and self-signed certificates on demand if the px5g
   8 keymaster library is available. Both nixio and px5g are libraries created
   9 by the LuCI developers.
  10
  11
  12 *** Configuration ***
  13 LuCId uses the UCI Universal Configuration Interface as configuration backend.
  14
  15 There are 4 types of configuration sections and one named section defined:
  16 The main section of type "lucid" defines the basic framework parameters of LuCId
  17 These include:
  18         * pollinterval: Internal polling interval
  19         * threadlimit: Overall maximum number of child processes
  20         * daemonize: Whether to daemonize at startup
  21         * debug: Whether to enable debug output in syslog
  22
  23
  24 The "tcpserver" section type provides the framework for TCP servers:
  25 Parameters:
  26         * entrypoint: Lua module entrypoint (provides a prepare_daemon function)
  27
  28 The "daemon" sections define instances of servers.
  29 Parameters may include:
  30         * slave: Server slave
  31         * publisher: Publishers to be served by this daemon
  32         * enabled: Flag (0/1) whether this daemon should be started
  33         * address: List of ports / addresses to be bound too, if applicable
  34         * encryption: Flag (disabled/enabled) whether to enforce encryption
  35         * tls: Reference to the TLS configuration section to use
  36
  37 The "...Publisher" sections define services to be published through daemons.
  38 Publishers definitions should be daemon and protocol independent whenever
  39 possible. Publishers should also implement access restrictions for certain
  40 network interfaces and for specified UNIX user accounts.
  41 Publishers usually define but are not required to use the following Parameters:
  42         * name: Published Name
  43         * physical: Physical source path
  44         * virtual: Virtual resource path
  45         * domain: Any kind of domain or realm specification
  46         * read: ACL containing entities allowed to read the given resource
  47         * write: -"-
  48         * exec: -"-
  49
  50 The "tls" sections describe TLS security specifications for TCP servers.
  51 Parameters:
  52         * key: Private Key file
  53         * cert: Certificate file
  54         * type: Type of certificate and key files (pem, asn1)
  55         * generate: Flag (0/1) to determine whether LuCId should generate
  56         keys and self-signed certificates if the certificate is not available and
  57         the px5g RSA Keymaster is available
  58
  59
  60
  61 *** Workflow ***
  62 In the preparation phase LuCId loads its configuration using the specification
  63 given above and prepares its servers, daemons and publishers. It also allocates
  64 resources such as binding sockets or preparing encryption credentials.
  65 If everything could be setup correctly LuCId will daemonize - if requested. If
  66 any errors occur in the preparation phase, LuCId will write to the system logger
  67 and exit.
  68
  69 After daemonizing the main process is responsible for keeping a list of
  70 file descriptors that LuCId is polling regularly to handle incoming data events.
  71 Data events are for example new TCP connection attempts which could cause the
  72 superserver to fork a new process and invoke a registered handler.
  73
  74 Whenever a sub-process is about to be generate LuCId checks if given resource
  75 limits are still met.