Configuration

Environment Variables

LAppS recognizes following environment variables, if those are not set in environment then the default values are used:

• LAPPS_HOME - root of LAppS installation (default value: /opt/lapps)
• LAPPS_CONF_DIR, - directory where the config files reside (default value: /opt/lapps/etc/conf)
• WS_CONFIG - name of the JSON file with WebSockets Server configuration (default value: ws.json)
• LAPPS_CONFIG - name of the JSON file with LAppS configuration (default value: lapps.json)

Configuration files

ws.json - configuration file for WebSockets Server behavior

There are some new options, available since 0.8.0, please beware that the bellow config file may include them. Read the options descriptions afterwards, the options which were added in 0.8.0 are tagged.

{
  "listeners" : 1,
  "connection_weight": 0.7,
  "ip" : "0.0.0.0",
  "port" : 5083,
  "workers": {
    "workers" : 3,
    "max_connections" : 10000,
    "auto_fragment" : false,
    "max_poll_events" : 256,
    "max_poll_wait_ms" : 10,
    "max_inbounds_skip" : 50
  },
  "acl" : {
    "policy" : "allow",
    "exclude" : []
  },
  "lapps_config_auto_save" : true,
  "tls" : true,
  "tls_client_version" : 4,
  "tls_server_version" : 4,
  "tls_certificates" : {
     "ca" : "/opt/lapps/etc/ssl/cert.pem",
     "cert" : "/opt/lapps/conf/ssl/cert.pem", 
     "key" : "/opt/lapps/conf/ssl/key.pem"
  }
}

• listeners - number of listeners to start. This attribute affects the speed of inbound connections acceptance.
• connection_weight - defines the connection weight in comparison to IOWorker's Event Queue size. This attribute affects internal load balancer, that chooses which IOWorker to use based on amount of connections vs event queue length.
• ip - Interface to bind to.
• port - Port to listen on.
• workers.workers - number of IO workers. This attribute is the number of parallel IO operations at a time.
• workers.max_connections - max connections per worker, exceeding connections will be declined.
• workers.auto_fragment - Enable or disable auto-fragmentation of outbound messages. false by default.
• workers.max_poll_events - [added in 0.8.0], positive integer (int32_t max), tuning option for maximum amount of events pilled at once. Dictates the maximum amount of file descriptors the epoll() may put into poll vector. There is no reason to poll all the events at once. This is a trade-off between calling epoll() too many times and to fill the events array with too many values at once. IOWorker will loop through the all events it have received from epoll, some of which may already be outdated.
• max_poll_wait_ms - [added in 0.8.0], positive integer (uint32_t max), trade-off between waiting in epoll() for available events (ignoring the new inbound connections in this time) and calling the epoll() multiple time thus switching the context from userland to kernel and back.
• max_inbounds_skip - [added in 0.8.0], positive integer (size_t), the default behavior of the IOWorkers, is to try and receive the new connections from inbound queue, however several thousands new connections per second may be pushed from the other side of this queue in this time. The value u will use here, will force the IOWorkers to abandon wait-less behavior once in a while [value], and retrieve outstanding inbound connections.
• acl.policy - default ACL policy. Possible values: allow, deny (default value: allow).
• acl.exclude - array of string values representing IP addresses of endpoints or networks excluded from default policy.
• tls - must be true if LAppS was build with tls support, false otherwise.
• tls_client_version - [added in 0.8.0], available options: 3 - TLSv1.2, any other value for TLSv1.3. Only effective for services which are using cws module.
• tls_server_version - [added in 0.8.0], available options: 3 - TLSv1.2, any other value for TLSv1.3. Does not affect tls_client_version. Be aware that you are probably going to need a real properly signed certificate, signed by known authority if you use TLS 1.3 and if you are going to have browser clients. I could not force Firefox or Chrome to connect to the server with TLS 1.3 enabled with my self signed certificate (there may be some other reason for this issue though).
• tls_certificates.ca - path to CA certificate provided by LibreSSL
• tls_certificates.cert - path to certificate
• tls_certificates.key - path to key file

lapps.json - LAppS configuration file

{
  "directories" :  {
     "applications" : "apps",
     "app_conf_dir" : "etc",
     "tmp": "tmp",
     "workdir": "workdir"
  },
  "services" : {
    "console": {
      "acl": {
        "exclude": [
          "192.168.13.0/24"
        ],
        "policy": "deny"
      },
      "auto_start": true,
      "instances": 1,
      "standalone": false,
      "max_inbound_message_size": 2097152,
      "preload": [
        "time",
        "murmur",
        "pam_auth",
        "mqr"
      ],
      "protocol": "LAppS",
      "request_target": "/console"
    }
  }
}
     

• directories - this section defines the relative path to applications root, their configuration, temporary directory and work directory. NOTE: only directories.applications is used now, all others are ignored.

  • direcories.applications - relative path to the applications. The value of this configuration parameter is used in composing LUA_PATH environment variable together with the service name.

• services - key-value configuration of the applications. The key is the application name ("console" in above example), hearafter: {name}.

  • services.{name}.internal - It is replaced with standalone keyword since 0.9.0. The values are true or false. Please see Applications section for details on difference between standalone and reactive services
  • services.{name}.request_target - the request target of WebSocket URI: wss://127.0.0.1/console. Every application must have its own unique request target. Using the same target for different applications will result in undefined behavior.
  • services.{name}.protocol - the application protocol raw or LAppS
  • services.{name}.instances - number of in-parallel working exemplars of the application.
  • services.{name}.max_inbound_message_size - Limit the size of inbound messages (in bytes). Optional.
  • services.{name}.acl - ACL settings for the service.
  • services.{name}.acl.policy - default policy, available values: allow, deny
  • services.{name}.acl.exclude - array of ip addresses to exclude from policy.
  • services.{name}.preload - an array of modules to preload before service starts. See Internal Modules section for details.
  • services.{name}.extra_headers - a JSON object representing a key-value map of additional HTTP headers, these will be provided to client on connection in additional to standard ones.
  • services.{name}.depends - a JSON array of strings consisting of subordinate service names. All the services listed in depends are to be started before the service providing depends attribute in the service description

An example of a service configuration with with extra_headers

"echo": {
      "auto_start": true,
      "instances": 1,
      "standalone": false,
      "max_inbound_message_size": 16777216,
      "preload": null,
      "protocol": "raw",
      "request_target": "/echo",
      "extra_headers" : {
        "Service" : "echo",
        "Strict-Transport-Security" : "max-age=31536000; includeSubDomains"
      }
}

An example of service dependencies. Service "echo_lapps" depends on service "time_broadcast". The "time_broadcast" service will be started by LAppS first.

"services" :  "echo_lapps": {
      "acl": {
        "exclude": [],
        "policy": "allow"
      },
      "auto_start": true,
      "instances": 3,
      "standalone": false,
      "max_inbound_message_size": 2097152,
      "preload": [],
      "protocol": "LAppS",
      "request_target": "/echo_lapps",
      "depends" : [ "time_broadcast" ]
    },
    "time_broadcast": {
      "auto_start": true,
      "instances": 1,
      "standalone": true,
      "preload": null
    }
}