Configuration

The Configuration Console

The LiveSwitch Configuration Console is a Web Application which makes managing your servers, applications, and channels easier than ever. Once you have completed your installation, assuming you installed a Gateway, you can find your Console running on your Gateway's localhost at http://localhost:9090/admin. This guide introduces you to the Console and its features. There are several important concepts to cover before we go on, so that you understand what it is you are configuring, and how it applies to your LiveSwitch infrastructure.

Concepts

You already know what Gateways, Media Servers, and SIP Connectors are, but the Console deals with some configuration entities that may be new to you. The configuration entities are used to configure your global environment, your deployment specific environment(s), and your client application environment(s). 

  • Site - global configuration, which is really just your license key and secondary (ephemeral) Redis cache configuration.
  • Deployments - pertains to your server-side deployments (Gateways, Media Servers, and SIP Connectors).
  • Applications - client application shared secret and global settings.
  • Channels - subordinate to a given application, channel configuration is specific to particular channels joined by your clients and is focused primarily on specifying media settings.

These configuration entities are first class concepts in the Console. With the exception of channels, they have their own prime spot in the top level navigation. Channels are special because they belong to an Application, and as such are listed as part of their Application's page.

This has been a brief introduction to the Console's configuration entities, read on for a more comprehensive discussion on configuring the available configuration properties of your SiteDeploymentsApplications, and Channels. This guide also introduces the remaining top level pages of your Console. These are the Home page, the Server Listing page, the API Keys page, the Certificates page, and the Change Password page.

Home

You Home page is the first page you will see whenever you log in to the Console. It is a landing area, and it also provides you with a brief status overview of your system health. The status overview informs you of two very important pieces of information:

  1. How many Media Servers are currently operational, and
  2. The secure status of your v1 API.

LiveSwitch Status Overview

If your v1 API does not have authentication enabled, then the above message will appear as a warning. Clicking this message takes you to the API Keys page, which has an area at the top allowing you to opt-in to v1 API authentication. More information is discussed in the API Keys section.

In the case that you have no connected Media Servers the message above will appear as a warning. This is because no connected Media Servers means that your clients cannot connect in either SFU or MCU mode. Clicking this message takes you to the Servers Listing page, which provides a handy help link to the Media Servers listing documentation where we discuss how to resolve the issue.

You may also notice that the Console has an alert area in the title bar in the shape of a bell. From any page in the Console, clicking on the bell  displays your system status, and allows you to click a status to navigate and gain more information about the particular status alert.

Servers Listing

Your Server Listing page shows you the LiveSwitch server environment. It lists out your Gateways, Media Servers, and SIP Connectors.

Gateways

Your Gateway listing shows the Gateways that are operational in your LiveSwitch infrastructure. You can click the arrow beside each listed Gateway to get more information such as the architecture, core count, etc.

Troubleshooting  - No Gateways Connected

In the case that you have no Gateways running you will see a message to that affect in the listing. This should be impossible, as your Console is using a Gateway to communicate with your backend. If this occurs please contact support@frozenmountain.com.

Media Servers

Your Media Server listing shows the Media Servers that are registered with a Gateway in your LiveSwitch infrastructure. You can click the arrow beside each listed Media Server to get more information such as core count, current connection details, etc.

Troubleshooting  - No Media Servers Connected

This is potentially a serious issue as it means that no client can get an SFU or MCU connection. The most likely causes are:

  1. You did not install a Media Server. In this case please see the Installation guide.
  2. You have misconfigured you serviceBaseUrl, which is how your Media Servers communicate with your Gateway. See the Deployment Configuration section for more information.

SIP Connectors

Your SIP Connector listing shows the SIP Connectors that are registered with a Gateway in your LiveSwitch infrastructure. You can click the arrow beside each listed SIP Connector to get more information such as the architecture, core count, etc.

Troubleshooting  - No SIP Connectors Connected

Please note that this is not necessarily an issue. Many use cases do not require a SIP Connector, and if you have never installed a SIP Connector then this message is perfectly normal. The most likely causes are:

  1. You did not install a SIP Connector. Again, you do not need to provide a SIP Connector if your use case does not require SIP support. If you do then please see the Installation guide.
  2. You have misconfigured you serviceBaseUrl, which is how your SIP Connectors communicate with your Gateway. See the Site Configuration section for more information.

Administrative User

The Configuration Console supports a single user. This is the user that you set up as step 3 of the Initialization Wizard [link this]. This user has full administrative privileges and can access all configuration options supported by the Console.

Note that this user account is specific to accessing your Configuration Console and is distinct from any other Frozen Mountain user account that you may have.

Configuration Entities

Site Configuration

The "Site" configuration manages all global configuration properties. Global properties are:

Redis Configuration

Redis Configuration Connection String

During installation you provided a connection string to a Redis instance which is used to store all of your persistent data. This is the Configuration Connection String. This connection string is configured per server in a JSON configuration file and it is not editable from the Console. For more information on managing the Configuration Connection String please see the discussion in our Advanced Topics. For improved performance you can configure another Redis instance as a cache. This Redis Cache Connection String can be managed through your Console.

Redis Cache Configuration

In addition to your Configuration Connection String, you can also provide a connection string to a secondary Redis instance to be used as ephemeral (cache) storage.

Best Practice

Note that it is considered best practice to configure the secondary Redis Cache. In a production environment this can impact performance dramatically.

License Key

Your LiveSwitch license key which is available from your Frozen Mountain Account page. You set this as part of the Initialization process, but you can update it at any time on your Site configuration page. Please copy and paste the entire license key into the provided text area and ensure you have no additional whitespace.

Advanced Path Configuration

Read only properties telling you the server paths used for signalling and administration. These paths are relative to your Gateway URL and are not configurable at this time.

Sync Path - The signalling endpoint for clients and servers (e.g. /sync).

Admin Path - REST endpoints and Console (e.g. /admin).

Deployment Configuration

The Deployments section lists and allows you to edit all the Deployment configurations you have created.  Deployment configurations contain all your server configuration settings.  At least one Deployment configuration is required and will be the default for all servers if not explicitly overridden.

Deployment Config

To change a server to use a deployment other then the default, you need to edit the configuration file on that server. See Server Specific Configuration for more information.

Deployment Name

This is the name of the deployment as displayed in the listings page.  This is also the name that you will use in the Server Specific Configuration to configure a deployment other then the default for the server.

Default Deployment

One deployment will always be the default configuration.  This deployment is used by services that have no explicit deployment configured.  You can change which deployment should be used as the default from the listing page.

Base URLs Configuration

The Service Base URL indicates the entry point for the Gateway (e.g. http://localhost:8080) and is used by Media Servers and SIP Connectors.  The path relative to the Service Base URL is configured in the Advanced Path Configuration section.

Reporting Interval

The Report Interval specifies, in seconds, how frequently to update the connection information for clients that are using the legacy/v1 REST API endpoints.

Logging Configuration

LiveSwitch provides a rich logging framework that supports many different capabilities.

  • Console logging logs to the terminal when you start the server as an application, instead of as a service.
  • File logging logs to a file on the local server.  The defaults location is: %ProgramData%\Frozen Mountain Software\-service-\ for Windows, and /var/log/fm/liveswitch/-service-/ for Linux.  You can override this to any directory.
  • Syslog logs to the system message logging.  The target attribute is the IP where the syslog is sent.  The default is 127.0.0.1.
  • Log Stash logs are sent to the specified the Logstash server.

  • Cloudwatch logs to AWS CloudWatch logging. See the Configuring the CloudWatch Log Provider section below for more information.
Levels

Logging statements have an associated level of severity. Possible log levels are: VERBOSE, DEBUGINFOWARNERROR, and FATAL. The severity level indicates the importance of the message. The levels are, from most severe to least severe:

  • FATAL: The message indicates a fatal application error; the application will need to shut down and no recovery actions are possible.
  • ERROR: The message indicates a normal application error (ie: timeouts, bad user input); this is a normal error state and usually it is possible to proceed.
  • WARN: The message indicates that something abnormal occurred but that the application was not negatively affected; this is used for unexpected values, deprecations or abnormal application state.
  • INFO: This is a trace message; it describes what is going on in the SDK.
  • DEBUG: This is a diagnostic message; it is similar to the INFO level but is used for outputting detailed parameters or for "spammy" messages.
  • VERBOSE: This is a diagnostic message; it is similar to the DEBUG level but is used for outputting extremely low level detailed tracing messages. It is generally not recommended to configure verbose logging.

The Level attribute allows you to set the level of logs you want displayed.  In production, you may want to display no message, and in development, you may want to display all diagnostic messages.

Configuring the CloudWatch Log Provider

This provider dumps the logs directly into a specific AWS CloudWatch log group.

Required attributes are:

  • AWS Region: The CloudWatch region to send the logs.
  • Log Group: The CloudWatch log group to send the logs to.

Basic access configuration requires two attributes:

  • Access Key: Your AWS access key.
  • Secret Key: Your AWS secret key.

Alternatively you can configure authentication via profile:

  • Deployment Name: The deployment name in which to try and load from an AWS credential file.
  • Deployment Path: The path to a AWS credential file. If missing, the default path is used.

Should you choose not to supply any of accessKeysecretKey, or the profile attributes, then AWS auto-detection is turned on if the service is running on EC2 or ECS. For ECS, the task execution role is used, so you must ensure it has CloudWatch permissions. For EC2, the instance profile role is used if available.

Production Environments

Best Practise: For production environments it is highly recommended to set your logging level to INFO or higher to minimize performance issues.

Audio/Video Recording Path

This property allows you to specify the path where your recordings will be stored.  To enable recording, update the Channel Configuration.

Clustering

LiveSwitch supports media server clustering, which allows multiple media servers to work together to handle higher traffic volumes than they would be able to alone. Clustering is enabled by default, and all media servers that are connected to a gateway or pool of gateways will automatically attempt to cluster.  There are a few settings you configure to control how your servers are clustered:

  1. CIDR - LiveSwitch media servers in a cluster communicate with each other over TCP sockets. By default, clustering is performed on port 8445 for the cluster connection. If port 8445, is not available, media servers will incrementally try additional port values until either one is successful or until it is clear that clustering is not possible. For instance, if 8445 is available, a media server will try 8446, 8447, etc. in turn until one is successful. Media servers self-determine which IP addresses they bind to these sockets, and generally will use the first one of their interfaces that work.  This is not always ideal. You can configure the binding behaviour by specifying the CIDR attribute.  If specified, a media server will only bind to IP addresses in the specified subnet.
  2. Port - You can change the default port that a media server will listen on by specifying the port attribute. Note - if you specify a port attribute, a media server will only ever listen on a single port. This means that if the port is unavailable, the media server will not attempt to cluster on a different port.
  3. Strategy - You have three options for the strategy that is employed to assign clients to a clustered media server:
    1. Round Robin - Sequentially go through each media server to assign the next client.
    2. Spill Over - Send all clients to the same media server until a threshold is met and then switch to the next media server.
    3. Least Connections - Send the next client to the media server with the least number of active connections.
Capacity Threshold Triggers

You can configure the thresholds that are used on a media server to determine when it is considered "over capacity".  Once a media server is over capacity, the gateway service will attempt to assign clients to a different media server instance.  The thresholds are:

  1. CPU - This value is expressed as a percentage of CPU use.  If the cpu usage exceeds this threshold value, the media server will be considered over capacity.
  2. Memory - This value is expressed in bytes.  If the memory usage exceeds this threshold value, the media server will be considered over capacity.
  3. Bandwidth - This value is expressed in Mbps.  If either upstream or downstream bandwidth exceeds this threshold value, the media server will be considered over capacity.
  4. Delay - The delay threshold configures how long your media server will remain unavailable before becoming available for new connections. Without this setting you could easily end up with a server thrashing between being over capacity, recovering some resources, accepting more connections, and then going over capacity again. Configuring the delay provides a buffer where the server will remain unavailable even as resources are recovered. This means that when the delay expires, and the server starts accepting new connections, the server is less likely to immediately go over capacity again. The longer the delay, the longer you are giving your server to recover.
  5. Failed Connections - This value is expressed in the number of failed connections.  If the number of failed connections exceeds this threshold value, the media server will be considered over capacity.
  6. Failed Connections Expiry - This value is expressed in seconds.  It specifies the time period to consider for Failed Connections.

SIP Configuration

Dial Plan

The two Webhook URLs are used to specify HTTP or HTTPS endpoints that will be hit when a call does not match any of the dial plan's mappings.

Port

Overrides the default SIP port.

Port

Unless you have a specific reason to alter the port, you should leave it as 5060.  Modifying this can cause confusion, as many applications will expect the port to be 5060.

Trunk Configuration

You must have an account with a SIP provider to use the LiveSwitch SIP Connector. There are several providers that provide free trials, which you can use to get started. Once you have a provider, you can configure them in this section to tell the LiveSwitch SIP Connector how to connect with them.

  • Domain - The SIP provider domain.
  • Transport - The protocol to use to connect to the SIP provider.
  • Register - Whether or not this SIP provider sends a registration request.
  • Can Terminate - Whether or not we can make outbound calls from this SIP provider.
  • Username - SIP Provider credentials.
  • Password - SIP Provider credentials.
  • Authorization Id - Some SIP providers use an auth id in addition to the username and password. 

Webhook Configuration

Webhooks allow you to extend LiveSwitch functionality by hooking your own processing into events from each server.  All servers provide access to Started and Stopped events. The Media Server and SIP Connector also provide access to Registered and Unregistered events.  Add a new webhook by clicking the NEW button and supplying:

  • Name - A human readable name of the webhook (does not have to be unique).
  • URL - The server to POST event information to (both HTTP and HTTPS are supported, but HTTPS is recommended).
  • Event Triggers - The Server level events will trigger a POST to your webhook.
  • Batch - POST multiple events in a single call. Without this set each event will result in a separate call.
  • Reliable - In the event of a failure, continue trying until successful.

External STUN URLs Configuration

Media Servers can specify up to two external STUN servers to use to automatically discover their publicly routable IP address and port. This may be necessary when they are behind a NAT and do not have a public IP address.  Frozen Mountain provides a STUN/TURN server available at stun.frozenmountain.com for demo purposes only. Other public STUN servers: stun.l.google.com:19302 and stun.services.mozilla.com.

Advanced Configuration

HTTP/HTTPS Bindings

HTTP/HTTPS Bindings

Editing these settings can break your service deployments in such a way that the only recovery path is to edit fields in Redis directly. Only make changes to this configuration if you are sure of what you are doing.

These are used to configure the ports on the Gateway that clients will connect on.

  • CIDR: Used to restrict the interfaces for binding. When empty, will bind on all interfaces. (optional)

  • Port: The port to bind.

  • ‘Apply to Sync’ and 'Apply to Admin': Restrict which bindings apply to Sync and Admin. See Advanced Path Configuration.

  • Certificate: Select one of the configured Certificates to apply to this binding (HTTPS only).

TURN/TURNS Bindings

These are used to configure the bindings for the embedded TURN server.  See here for more information.

  • CIDR: Used to restrict the interfaces for binding. When empty, will bind relay services on all interfaces. (optional)

  • Port: The port used for relay connections.

  • Protocol: Networking protocol used for communication between clients and relay server.  Relay candidates on the server will still be advertised as UDP candidates when TCP is chosen for communication between the client and the server.

  • Certificate: Select one of the configured Certificates to apply to this binding (TURNS only).

Application Configuration

Your Applications page displays a listing of your configured Applications. Applications consist of one or more channels. Channels are what your clients join, and are used for specifying the media configuration clients make use of for SFU or MCU connections. Applications also specify some useful configuration properties that will be shared by all clients, regardless of which channel they join. These properties are SIP Mappings, Webhook Configurations, and the Application's Shared Secret. Read on for more information.

If you have a "Default Application" configured, it will be displayed at the top of the listing page in its own section. Let's discuss what this "Default Application" is, and why it is not recommended.

The Default Application

The Default Application is a legacy pattern. It is deprecated, but still supported at this time for customers that are migrating from 1.2.x (or older) installations. Older versions of LiveSwitch would allow a client to join a conference without specifying a particular application. In this case the client would join a special default application which used a special '*' identifier as its ID as long as they supplied the correct shared secret. The problem with this approach is that it is relatively simple to brute force the shared secret. With no default Application, attackers must brute force two values, the shared secret AND the name of the Application (its ID), making it exponentially harder for a rogue client to piggy back on your LiveSwitch server infrastructure.

Deprecated - Default Application

Making use of the "Default Application" pattern is NOT recommended. It is provided only for legacy purposes.

Default Application Status

At the top the page of a given Application a message is displayed informing you whether or not this Application is set to be used as your default. For the reasons discussed above, you are also warned that this is not best practice. That said, you can click the SET button to have any of your Applications set as your default should you choose to do so. Only one Application can act as the default at a given time, but again, it is recommended that you do NOT configure a default Application. Instead, configure all of your clients to be explicit about the Application AND Channel they join. 

SIP Inbound Mapping Configuration

If you are using SIP integration (via SIP Connector), then we require a way to map incoming SIP Invites to a particular Channel. Provide the SIP URI and the Channel to which you wish to route incoming SIP requests. For example, you can add configuration to route invites from user@host.port into the my-awesome-channel channel.

Webhook Configuration

Webhooks allow you to extend LiveSwitch functionality by hooking your own processing into Application level events. These events are Client RegisteredClient Unregistered, and Client Updated. Add a new webhook by clicking the NEW button and supplying:

  • Name - A human readable name of the webhook (does not have to be unique).
  • URL - The server to POST event information to (both HTTP and HTTPS are supported, but HTTPS is recommended).
  • Event Triggers - The Application level events will trigger a POST to your webhook.
  • Batch - POST multiple events in a single call. Without this set each event will result in a separate call.
  • Reliable - In the event of a failure, continue trying until successful.

Shared Secret

The Shared Secret is known by both your Application Configuration, and the clients trying to join an Application and Channel. It is used to authenticate client join requests. See the Client docs for more information on configuring shared secrets in your LiveSwitch client side code. 

Channel Configuration

Channels provide a mechanism for specifying media configuration used by client MCU and SFU connections. Channels belong to an Application, and are listed at the end of the Application's page.

Within the context of an Application clients can have many different use cases. Channels are the best way to meet the requirements of a given use case. For example, clients might join a Channel to stream audio/video from their mic and camera, and join a different Channel specifically to stream screen capture video. The first channel needs to configure audio/video encoders, but the latter need not configure audio and it may specify a different video encoding configuration. Channels support many different configuration properties. Read on for a comprehensive discussion. However, let's first discuss how Channel Configurations are matched to a client requesting to join a Channel.

The Channel Pattern and the Default Channel

Channels have a Channel Pattern instead of a name, and this pattern supports the wildcard '*' character. When a client requests to join a Channel the Gateway will look at all of the Channels available and pick the Channel that best matches. Matches are attempted in the order specified in your Application's Channel listing. If you want to change the attempted matching order you can just drag Channels around in the listing to get the order that works best.

One special case is provided here - the "Default Channel". The Default Channel has a Channel Pattern equal to the wildcard character '*'. As you might imagine, this will match anything and everything. The Default Channel is provided for you when you create an Application. The Default Channel is always last in the list of an Application's Channels meaning that it will match last. It is a catch-all, which serves to ensure your clients will always have a Channel Configuration applied to their connections. You can configure your Default Channel to meet your most general requirements.

Default Channel vs Default Application

If you have read the section on The Default Application then you might have some concerns about this Default Channel feature. Please note that since the Shared Secret exists at the Application level, and not at the Channel level, the Default Channel does not suffer from the same security concern.

Now that you understand what Channels are, and how they can be used, let's consider all of the configuration properties provided by the Channel Configuration.

Audio Codecs

The Audio Codecs Configuration allows you to specify which audio codecs are supported by the LiveSwitch Media Server. The available codecs are:

  • Opus: Enabled by turning the switch to the on position. You can additionally set the bitrate with the Max Bitrate property. This value is in kbps.
  • PCMU: Enabled by turning the switch to the on position.
  • PCMA: Enabled by turning the switch to the on position.

Please note that bitrate here (in Kbps) is a downstream rate, which means that if you specify 1024, then this is the maximum rate that will be sent in the downstream.

Codecs

Note that if you disable too many codecs, the LiveSwitch Media Server may be unable to accept connections.

Video Codecs

The Video Codecs Configuration allows you to specify which video codecs are supported by the LiveSwitch Media Server. The available codecs are:

  • VP8: Enabled by turning the switch to the on position. You can additionally set the bitrate with the Max Bitrate property. This value is in kbps.
  • VP9: Enabled by turning the switch to the on position. You can additionally set the bitrate with the Max Bitrate property. This value is in kbps.
  • H264: Enabled by turning the switch to the on position. You can additionally set the bitrate with the Max Bitrate property. This value is in kbps.

Please note that bitrate here (in Kbps) is a downstream rate, which means that if you specify 1024, then this is the maximum rate that will be sent in the downstream.

Codecs

Note that if you disable too many codecs, the LiveSwitch Media Server may be unable to accept connections.

SFU Configuration

SFU Configuration allows you to set configuration options for the LiveSwitch Media Server when it is running in SFU mode. You are not able to set the video or audio output, as the SFU does not actually perform any processing of audio and video streams - it merely forwards them. You can however, configure is the Video Input Max Bitrate and Audio Input Max Bitrate for participants while in an SFU session. The value of these properties is in kbps.

Please note that bitrate here (in Kbps) is an upstream rate, which means that if you specify 1024, then this is what the Media Server will attempt to negotiate with participants.

MCU Configuration

MCU Configuration allows you to set configuration options for a LiveSwitch Media Server when it is running in MCU mode. Among other things, this allows you to define how you want the output video to be formatted by the multiplexer. To configure this you can set both the Frame Width and Frame Height dimensions, and the Target Frame Rate of the video that the MCU outputs.

For video resolutions, you should try to stick to common resolutions, as not all combinations are valid for all codecs. For example, don't enter 147x933. You should also keep your frame rate to a reasonable value. Anything beyond 30 frames per second will require a powerful server to keep up in larger video conferences.

Another aspect that you can configure is the Video Input Max Bitrate and Audio Input Max Bitrate for participants while in an MCU session. This is useful to limit the amount of bandwidth that the MCU consumes. The value of these properties is in kbps.

Please note that bitrate here (in Kbps) is an upstream rate, which means that if you specify 1024, then this is what the Media Server will attempt to negotiate with participants.

Lastly, you will notice a Type property. This refers to the type of graphics rendering engine used by the MCU. Only Skia is supported at this time. You can configure several of the Skia graphics rendering engine properties including AntialiasingDither, and applied Filter Quality.

Bandwidth Adaptation Policy

Set the Bandwidth Adaptation Policy property to Enabled to turn on bandwidth adaptation for your SFU and MCU connections. Also, in your native client code, you must set BandwidthAdaptationPolicy to Enabled on your VideoStream.

Native Bandwidth Adaptation is Experimental

Note that in the native platforms bandwidth adaptation is still experimental and is not recommended for AudioStreams at this time.

Bandwidth Adaptation in Browser Clients

Bandwidth adaptation is enabled by default in WebRTC-capable browser clients (Chrome, Firefox, Edge, and Safari).

Connection Statistics Interval

The Connection Statistics Interval property determines the granularity in milliseconds at which connection statistics are sampled.

Performance Consideration

It is highly recommended not to set this value too low. Setting it to less than 1000 ms could have severe CPU performance implications.

Audio/Video Recording Enabled

This configuration property controls whether or not the LiveSwitch Media Server records media for any clients in the Channel. To enable recording move the switch to the Enabled position. The recording path can be customized in your Deployment Configuration. Otherwise, the server's default temp directory will be used.

Note that in a peer to peer session, no recording is performed. This is because in this type of session, no users are connected to the LiveSwitch Media Server itself. If you wish to record a session, you must ensure that it is an SFU or MCU session.

SIP Outbound Caller ID Configuration

Outbound caller ID can now be set for your SIP Connector using the SIP Outbound Mapping Configuration properties Display Name Pattern and Number Pattern. You can configure both of these properties if you wish. A SIP URI may contain name and number segments. These two pattern properties act as a template so you can set your SIP URI name and number segments to whatever you want. Using `{}`, they swap in variables from the ClientInfo object. For example: "{userAlias}-{userId}" is a valid pattern.

Webhook Configuration

Webhooks allow you to extend LiveSwitch functionality by hooking your own processing into Channel level events. The Client events are Client Joined and Client Left. The Connection events are Connection InitializingConnection ConnectingConnection ConnectedConnection ClosingConnection ClosedConnection FailingConnection FailedConnection Updated, and Connection Stats Generated. Add a new webhook by clicking the NEW button and supplying:

  • Name - A human readable name of the webhook (does not have to be unique).
  • URL - The server to POST event information to (both HTTP and HTTPS are supported, but HTTPS is recommended).
  • Event Triggers - The Application level events will trigger a POST to your webhook.
  • Batch - POST multiple events in a single call. Without this set each event will result in a separate call.
  • Reliable - In the event of a failure, continue trying until successful.

API Keys

The API Keys page allows you to secure your v1 API and manage your API keys.

Securing Your v1 API

LiveSwitch 1.2.x (and lower) Gateways required that access to your administrative route be blocked by your firewall thus preventing unauthorized access to administrative functionality via the REST API. With LiveSwitch 1.3.x (and higher) this is still an option. However, you can alternatively use API Keys. To prevent a breaking change when migrating between 1.2.x and 1.3.x the v1 API is not secured by default. This ensures that any service currently using the v1 API will continue to do so without interruption.

Best Practice

It is considered best practice to secure your v1 API. 

After you have secured your v1 APIs, you will need add in API key to the header of your v1 API call.

CURL Example
curl -H "Accept:application/json" -H "X-API-Key: 8b45e287-6470-4727-81c6-39a2589e" -v https://localhost:9090/admin/api/v1.0/mediaservers

Managing API Keys

API Keys can be created in the Console from the API Keys page. To create an API key, click the New API Key button. You are required to provide a tag, which is simply a human readable label for a key. Note that tags need not be unique and can be edited at any time.

Revoking API Keys

You can revoke an API key at any time by deleting it. Be aware that any API call using a revoked key will return a 401 Unauthorized response from your Gateway.

Certificates

The Certificates page provides a central place to manage your certificates, which are necessary for configuring HTTPS and TURNS bindings. For more information on these secure bindings see the Deployment Configuration section. To support a variety of use cases, the Console provides three methods to manage certificates.

Supported use cases are:

  1. Wildcarded domains (typical) - Nice, convenient, central management for certificates. Your TURNS/HTTPS bindings make use of the certificates you have configured, and your certificates are issued for wildcarded domains, meaning they can be used across all your subdomains and it does not matter under which subdomain your server is actually running.
  2. Migration case - For certificates that existed in 1.2.x (or older) installs.
  3. Individual certificates per server - Certificates are not wildcarded, and you must refer to an actual certificate residing on a server somewhere.

Certificates, Bindings, and Deployments

 To make use of a certificate you MUST actually set up a Deployment Configuration with HTTPS/TURNS bindings using this certificate, AND configure the Deployment in your servers' JSON config. This last need only be done once, after that you can update certificates as needed, and use the Console to update the bindings for that Deployment. JSON config need not be updated in this case. For more information on configuring your servers with a Deployment Configuration please see the Deployment Configuration section.

To support these use cases the Console allows you to upload .PFX certificate files, or for certificates that you have placed on a server yourself you can refer to them by file path or by the certificate's hash (Windows Certificate Store).

Uploading Certificates from a Certificate File

This method supports the typical "wildcarded domain" use case. Under the File Certificates section of the page, click the NEW CERTIFICATE button to upload your (optionally password protected) .PFX certificate file.

Best Practice

It is considered best practice to manage your certificates using this method. When you upload a certificate file it is validated as part of the upload process, so any problems with the certificate are reported to you when you attempt to upload the certificate, which allows you to fix the issue immediately.

Specifying Certificates by Path

This method supports the "migration" and "individual cert per server" use cases. It is intended specifically for Linux servers. Under the Path Certificates section of the page, click the NEW CERTIFICATE button to specify the full file system path to your certificate. When your server starts up it will attempt to load this certificate from the file system.

Not Recommended

Be aware that certificates specified by file path cannot be verified by the Console. We have no way of knowing if your certificate configuration will work until the server for which it is configured attempts to load it from the file system. Wherever possible we recommend managing your certificates by uploading a .PFX file.

Specifying Certificates by Hash

This method supports the "migration" and "individual cert per server" use cases. It is intended specifically for Windows servers. Under the Hash Certificates section of the page, click the NEW CERTIFICATE button to specify your certificate's hash value. When your server starts up it will attempt to load this certificate from the Windows Certificate Store using this hash.

Not Recommended

Be aware that certificates specified by hash cannot be verified by the Console. We have no way of knowing if your certificate configuration will work until the server for which it is configured attempts to load it from the Windows Certificate Store. Wherever possible we recommend managing your certificates by uploading a .PFX file.