HTTP Server Configuration

EMQX Edge includes a built-in HTTP server that serves both the Dashboard web interface and the HTTP API. The following configuration controls how the server is exposed and secured, including the port, connection limit, authentication type, and optional TLS settings for HTTPS access.

Example Configuration

The following example configures the Dashboard to listen on port 8081, accept up to 32 concurrent connections, and require basic authentication. The default admin account is defined by username and password. Additional accounts are stored in the usernames and passwords arrays. For details, see Dashboard User Management.

http_server {
  port = 8081
  ip_addr = "0.0.0.0"
  limit_conn = 32
  username = "admin"
  password = "<encrypted-password>"
  auth_type = basic
  usernames = ["user1"]
  passwords = ["<encrypted-password>"]
  max_body = 65535
  ssl = {
    enable = false
  }
}

Configuration Items

Parameter	Type	Default	Description
port	Integer	8081	Port on which the HTTP server listens. Value range: 0 ~ 65535.
ip_addr	String	"0.0.0.0"	IP address on which the HTTP server listens.
limit_conn	Integer	32	Maximum number of concurrent requests the server can handle.
auth_type	Enum	"basic"	Authentication type for the HTTP server. Values: "basic", "jwt".
username	String	"admin"	Username for the default Dashboard login account.
password	String	—	Encrypted password for the default Dashboard login account.
usernames	Array	—	Usernames for additional Dashboard accounts. Each entry corresponds to the encrypted password at the same index in passwords. Managed via the Dashboard UI.
passwords	Array	—	Encrypted passwords for additional Dashboard accounts. Each entry corresponds to the username at the same index in usernames. Managed via the Dashboard UI.
max_body	Integer	65535	Maximum HTTP request body size (bytes).
jwt.public.keyfile	String	—	Path to the public key file for JWT verification. Required when auth_type is "jwt".

Enable HTTPS for the Dashboard

By default, the Dashboard is served over HTTP. If the Dashboard is accessible over an untrusted network, enabling HTTPS encrypts the connection and prevents credentials from being transmitted in plain text. To enable HTTPS, set ssl.enable = true and provide a valid certificate and key.

Note

HTTPS for the Dashboard is only supported in self-hosted deployments. You must provide your own certificate and key files.

SSL Configuration Items

Parameter	Type	Default	Description
ssl.enable	Boolean	false	Enables HTTPS for the Dashboard. When true, the Dashboard is accessible via https://.
ssl.key_password	String	—	Password for the private key file, if the key is password-protected.
ssl.keyfile	String	—	Path to the server private key file.
ssl.certfile	String	—	Path to the server certificate file.
ssl.cacertfile	String	—	Path to the CA certificate or CA bundle used to verify the peer/client certificate when ssl.verify_peer is true.
ssl.verify_peer	Boolean	false	Whether to require and verify a client certificate.
ssl.fail_if_no_peer_cert	Boolean	false	Whether to reject connections from clients that do not present a certificate. Only takes effect when ssl.verify_peer is true.

Prepare a Self-Signed Certificate

The following example generates a self-signed certificate for testing. Use a CA-issued certificate in production.

1. Create a san.cnf file:

   [req]
   default_bits       = 2048
   prompt             = no
   distinguished_name = dn
   req_extensions     = req_ext
   x509_extensions    = v3_ca
   [dn]
   CN = server
   [req_ext]
   subjectAltName = @alt_names
   [v3_ca]
   subjectAltName = @alt_names
   basicConstraints = CA:FALSE
   keyUsage = digitalSignature, keyEncipherment
   extendedKeyUsage = serverAuth
   [alt_names]
   DNS.1 = server

   The CN and DNS.1 values define the hostname (server) that the certificate is valid for. This hostname is used in subsequent steps.

2. Generate the certificate and key:

   openssl req -x509 -nodes -days 825 \
     -newkey rsa:2048 \
     -keyout server.key \
     -out server.crt \
     -config san.cnf

3. Place server.key and server.crt in a directory accessible to EMQX Edge, then update nanomq.conf:

   http_server {
     port = 8081
     ip_addr = "0.0.0.0"
     limit_conn = 32
     auth_type = basic
     ssl = {
       enable = true
       keyfile = "/etc/certs/https/server.key"
       certfile = "/etc/certs/https/server.crt"
       cacertfile = "/etc/certs/https/server.crt"
       verify_peer = false
       fail_if_no_peer_cert = false
     }
   }

4. Add the certificate to the trusted certificate store on the machine running the browser.

   • macOS:

     sudo security add-trusted-cert -d -r trustRoot \
       -k /Library/Keychains/System.keychain ./server.crt

   • Ubuntu/Debian:

     sudo cp ./server.crt /usr/local/share/ca-certificates/
     sudo update-ca-certificates

   On other operating systems, refer to your system documentation for adding a trusted root certificate.

5. Add the server hostname to /etc/hosts on the machine running the browser, replacing <ip-address> with the actual IP address of the EMQX Edge host:

   <ip-address> server

6. Restart EMQX Edge, reopen the browser, then open https://server:8081/.

Verify the HTTPS Configuration

To confirm that the Dashboard is being served over HTTPS correctly, run the following command. It checks that the server completes the TLS handshake and negotiates the http/1.1 application protocol via ALPN.

curl -v --cacert server.crt https://server:8081 2>&1 | grep -i alpn

The output should include:

ALPN: server accepted http/1.1