Search results

Edit on GitHub

Configuration

This part of the documentation focuses on the configuration of the server.

Start by locating the config.js file in the configuration folder, which depends on how you installed The Lounge.

Server settings

public

When set to true, The Lounge starts in public mode. When set to false, it starts in private mode.

  • A public server does not require authentication. Anyone can connect to IRC networks in this mode. All IRC connections and channel scrollbacks are lost when a user leaves the client.
  • A private server requires users to log in. Their IRC connections are kept even when they are not using or logged in to the client. All joined channels and scrollbacks are available when they come back.

This value is set to false by default.

host

IP address or hostname for the web server to listen to. For example, set it to "127.0.0.1" to accept connections from localhost only.

For UNIX domain sockets, use "unix:/absolute/path/to/file.sock".

This value is set to undefined by default to listen on all interfaces.

port

Set the port to listen to.

This value is set to 9000 by default.

bind

Set the local IP to bind to for outgoing connections.

This value is set to undefined by default to let the operating system pick its preferred one.

reverseProxy

When set to true, The Lounge is marked as served behind a reverse proxy and will honor the X-Forwarded-For header.

This value is set to false by default.

maxHistory

Defines the maximum number of history lines that will be kept in memory per channel/query, in order to reduce the memory usage of the server. Setting this to -1 will keep unlimited amount.

This value is set to 10000 by default.

https

These three settings are used to run The Lounge using encrypted HTTP/2 on the server side. This will fallback to regular HTTPS if HTTP/2 is not supported.

The available keys for the https object are:

  • enable
  • key: Path to the private key file.
  • certificate: Path to the certificate.
  • ca: Path to the CA bundle.

The value of enable is set to false to disable HTTPS by default, in which case the other two string settings are ignored.

Client settings

theme

Set the default theme to serve to new users. They will be able to select a different one in their client settings among those available.

The Lounge ships with a few themes (crypto, example, morning, and zenburn) and can be extended by installing more themes. Read more about how to manage them here.

This value needs to be the package name and not the display name. For example, the value for Morning would be morning, and the value for Solarized would be thelounge-theme-solarized.

This value is set to "example" by default.

prefetch

When set to true, The Lounge will load thumbnails and site descriptions from URLs posted in channels and private messages.

This value is set to false by default.

prefetchStorage

When set to true, The Lounge will store and proxy prefetched images and thumbnails on the filesystem rather than directly display the content at the original URLs.

This improves security and privacy by not exposing the client IP address, and always loading images from The Lounge and making all assets secure, which in result fixes mixed content warnings.

If storage is enabled, The Lounge will fetch and store images and thumbnails in the ${THELOUNGE_HOME}/storage folder.

Images are deleted when they are no longer referenced by any message (controlled by maxHistory), and the folder is cleaned up when The Lounge restarts.

This value is set to false by default.

prefetchMaxImageSize

When prefetch is enabled, images will only be displayed if their file size does not exceed this limit.

This value is set to 2048 kilobytes by default.

transports

Set socket.io transports.

This value is set to ["polling", "websocket"] by default.

leaveMessage

Set users’ default quit and part messages if they are not providing one.

This value is set to "The Lounge - https://thelounge.chat" by default.

Default network

defaults

Specifies default network information that will be used as placeholder values in the Connect window.

The available keys for the defaults object are:

  • name: Name to display in the channel list of The Lounge. This value is not forwarded to the IRC network.
  • host
  • port: Usually 6667 for unencrypted connections and 6697 for connections encrypted with TLS.
  • password
  • tls: Enable TLS connections
  • rejectUnauthorized: Whether or not the server certificate should be verified against the list of supplied CAs by your Node.js installation.
  • nick: Percent signs (%) will be replaced by random numbers from 0 to
    1. For example, Guest%%% may become Guest123.
  • username
  • realname
  • join: Comma-separated list of channels to auto-join once connected.

This value is set to connect to the official channel of The Lounge on Freenode by default:

defaults: {
  name: "Freenode",
  host: "chat.freenode.net",
  port: 6697,
  password: "",
  tls: true,
  rejectUnauthorized: true,
  nick: "thelounge%%",
  username: "thelounge",
  realname: "The Lounge User",
  join: "#thelounge"
}

displayNetwork

When set to false, network fields will not be shown in the “Connect” window.

Note that even though users cannot access and set these fields, they can still connect to other networks using the /connect command. See the lockNetwork setting to restrict users from connecting to other networks.

This value is set to true by default.

lockNetwork

When set to true, users will not be able to modify host, port and TLS settings and will be limited to the configured network.

It is often useful to use it with displayNetwork when setting The Lounge as a public web client for a specific IRC network.

This value is set to false by default.

User management

messageStorage

The Lounge can log user messages, for example to access them later or to reload messages on server restart.

Set this array with one or multiple values to enable logging:

  • text: Messages per network and channel will be stored as text files. Messages will not be reloaded on restart.
  • sqlite: Messages are stored in SQLite database files, one per user.

Logging can be disabled globally by setting this value to an empty array []. Logging is also controlled per user individually in the logs key of their JSON configuration file.

This value is set to ["sqlite", "text"] by default.

logs

User logging must be enabled per user, in their configuration file under $THELOUNGE_HOME/users/<user>.json. When enabled, logs will be stored in the $THELOUNGE_HOME/logs/<user>/<network>/ directory.

The available keys for the logs object are:

  • format: set to "YYYY-MM-DD HH:mm:ss" by default

  • timezone: set to "UTC+00:00" by default

useHexIp

When set to true, users’ IP addresses will encoded has hex.

This is done to share the real user IP address with the server for host masking purposes.

This value is set to false by default.

WEBIRC support

When enabled, The Lounge will pass the connecting user’s host and IP to the IRC server. Note that this requires to obtain a password from the IRC network that The Lounge will be connecting to and generally involves a lot of trust from the network you are connecting to.

There are 2 ways to configure the webirc setting:

  • Basic: an object where keys are IRC hosts and values are passwords. For example:

    {
      "irc.example.net": "password1",
      "irc.example.org": "passw0rd"
    }
    
  • Advanced: an object where keys are IRC hosts and values are functions that take three arguments (client, args, trusted) and return an object to be directly passed to irc-framework. For example:

    {
      "irc.example.net": (client, args, trusted) => ({
        username: "thelounge",
        password: "password1",
        address: args.ip,
        hostname: `webirc/${args.hostname}`
      })
    }
    

This value is set to null to disable WEBIRC by default.

identd and oidentd support

identd

Run The Lounge with identd support.

The available keys for the identd object are:

  • enable: When true, the identd daemon runs on server start.
  • port: Port to listen for ident requests.

The value of enable is set to false to disable identd support by default, in which case the value of port is ignored. The default value of port is 113.

oidentd

When this setting is a string, this enables oidentd support using the configuration file located at the given path.

This is set to null by default to disable oidentd support.

LDAP support

These settings enable and configure LDAP authentication.

They are only being used in private mode. To know more about private mode, see the public setting above.

The authentication process works as follows:

  1. The Lounge connects to the LDAP server with its system credentials.
  2. It performs a LDAP search query to find the full DN associated to the user requesting to log in.
  3. The Lounge tries to connect a second time, but this time using the user’s DN and password. Authentication is validated if and only if this connection is successful.

The search query takes a couple of parameters in searchDN:

  • a base DN searchDN/base. Only children nodes of this DN will be likely be returned;
  • a search scope searchDN/scope (see LDAP documentation);
  • the query itself, built as (&(<primaryKey>=<username>) <filter>) where <username> is the user name provided in the log in request, <primaryKey> is provided by the config and <filter> is a filtering complement also given in the config, to filter for instance only for nodes of type inetOrgPerson, or whatever LDAP search allows.

Alternatively, you can specify the bindDN parameter. This will make The Lounge ignore searchDN options and assume that the user DN is always <bindDN>,<primaryKey>=<username>, where <username> is the user name provided in the log in request, and <bindDN> and <primaryKey> are provided by the configuration.

The available keys for the ldap object are:

  • enable: when set to false, LDAP support is disabled and all other values are ignored.

  • url

  • tlsOptions: LDAP connection TLS options (only used if scheme is ldaps://). It is an object whose values are Node.js’ tls.connect() options. It is set to {} by default. For example, this option can be used in order to force the use of IPv6:
    {
      host: 'my::ip::v6',
      servername: 'example.com'
    }
    
  • baseDN: LDAP base DN, alternative to searchDN. For example, set it to "ou=accounts,dc=example,dc=com". It is not set by default, to use searchDN instead.
  • primaryKey: LDAP primary key. It is set to "uid" by default.

  • searchDN: LDAP search DN settings. This defines the procedure by which The Lounge first looks for the user DN before authenticating them. It is ignored if baseDN is specified. It is an object with the following keys:

    • rootDN: This bind DN is used to query the server for the DN of the user. This is supposed to be a system user that has access in read-only to the DNs of the people that are allowed to log in. It is set to "cn=thelounge,ou=system-users,dc=example,dc=com" by default.

    • rootPassword: Password of The Lounge LDAP system user.

    • ldapFilter: it is set to "(objectClass=person)(memberOf=ou=accounts,dc=example,dc=com)" by default.

    • base: LDAP search base (search only within this node). It is set to "dc=example,dc=com" by default.

    • scope: LDAP search scope. It is set to "sub" by default.

Debugging settings

The debug object contains several settings to enable debugging in The Lounge. Use them to learn more about an issue you are noticing but be aware this may produce more logging or may affect connection performance so it is not recommended to use them by default.

All values in the debug object are set to false.

debug.ircFramework

When set to true, this enables extra debugging output provided by irc-framework, the underlying IRC library for Node.js used by The Lounge.

debug.raw

When set to true, this enables logging of raw IRC messages into each server window, displayed on the client.