mod_external_services

mod_external_services allows clients to discover external services via XEP-0215: External Service Discovery. This is most commonly used to provide access to STUN and TURN services for use with Jingle.

Available starting with 0.12.0.

For the most common use case of providing STUN/TURN services, using mod_turn_external is easier.

Usage

modules_enabled = {
    -- Other modules
    "external_services"
}

-- list of services
external_services = {
    {
        type = "stun",
        transport = "udp",
        host = "stun.example.com",
        port = 9876
    }, {
        type = "turn",
        transport = "udp",
        host = "turn.example.com",
        port = 9876,
        secret = "hemligt"
    }
}

Configuration

Services are listed as items in external_services. Each item can have the a number of properties.

Basic properties

type: Type of service. stun, turn are common values.
transport: Which transport protocol the service is using. udp or tcp are common values.
host: DNS hostname or IP address where the service is provided. If missing, the config option external_service_host (defaults to the VirtualHost name) is used instead.
port: Service port. If missing, the config option external_service_port is used instead.
restricted: Boolean used to indicate that credentials are needed to access the service. Set automatically if password or secret is set.

Static credentials

If the service is to be provided with login credentials that are the same for everyone, they can be set with the properties username and password.

Dynamic credentials

The secret used to generate password per TURN REST API is specified with secret.

If a username prefix is needed, it is set in the username property.

The ttl property can be used to specify for how long the credentials are valid. Default is 1 day (86400 seconds).

Defaults

To reduce repetition, host, port, ttl and secret can be specified once using the options external_service_host, external_service_port, external_service_ttl and external_service_secret. To indicate where to use the secret, secret = true is used.

Thus these two examples are equivalent:

external_services = {
    {
        type = "stun",
        transport = "udp",
        host = "proxy.example.com",
        port = 9876
    }, {
        type = "turn",
        transport = "udp",
        host = "proxy.example.com",
        port = 9876,
        secret = "hemligt"
    }
}

---

external_service_host = "proxy.example.com"
external_service_port = 9876
external_service_secret = "hemligt"
external_services = {
    {type = "stun", transport = "udp"},
    {type = "turn", transport = "udp", secret = true}
}