Configuration settings

Eric Richardson edited this page Aug 5, 2015 · 3 revisions

StreamMachine uses Flatiron's nconf to load in its configuration. That means that configuration can be set via a JSON config file, environment variables or command line options.

For typical production settings, though, a config file will be your best choice. The config file must be valid JSON, so watch your commas, your quoted keys, etc.


  • Modes: Slave, Standalone

What port should we listen on for end-user connections?


  • Modes: Master, Standalone

What port should we listen on for Icecast source connections?


  • Mode: Master

Configures the master mode's master port and slave listening.

  • port: What port should the master listen on for slave connections and the admin UI/API?
  • password: Secret string used by slaves to authenticate themselves to the master server.


  • Mode: Slave

Tells the slave mode instance where to find its master.

  • master: URI for the master instance, prefixed with "ws://" to indicate that it is a WebSockets connection. Should include a query option of ?password=PASS, where PASS is the password set in the master section of the master server.


  • Mode: Standalone, Master

Configure a Redis server to use for persisting configuration changes.

  • server: URI for the Redis server (eg redis://localhost:6379). Can also have a database number at the end, such asredis://localhost:6379/1`.
  • key: (Optional) Key prefix. Defaults to StreamMachine


  • Modes: Master, Standalone, Slave

The log section takes nested configuration for each possible log output. Most of the time, a value of true will turn the logging output on with the default options, while a hash value will allow you to tweak the config settings.

All logging outputs will take a level key that determines what level of output messages will be included. Typical levels are error, alert, event, info, debug. In each case, selecting a level will also include all the levels above it (so debug would include info messages, event messages, etc).


If true, turns console logging on. Accepts any options supported by the Winston Console transport.


Writes messages to a log file. Accepts any options supported by the Winston File transport.


Sends logging messages to a Campfire chat room.

  • account: Campfire account
  • token: Campfire API token
  • room: ID number of the Campfire room to which messages should be posted


Logs request stats to a W3C-format log file that can be read by analytics packages designed for Shoutcast log output.

  • file: Path to the log file that should be written

Should use the request logger level.


  • Modes: Master, Standalone, Slave

The alerts object configures alert notifications. Alerts can be sent via email, and are also sent to the normal logging system with the alert level.


Sets up the server to use email to send alert notices. Uses Nodemailer internally to send emails, so most email options and supported configurations will come from that project.

  • mailer_type: Nodemailer transport to use for email. Supported options include SMTP, SES (Amazon's Simple Email Service) and sendmail (for a locally-configured Sendmail binary).
  • mailer_options: Options to pass to the transport. Defined by Nodemailer.
  • email_options: Options to merge into the generated email. Should include from and to.


Sends alerts to Pagerduty.

  • serviceKey: Pagerduty service key.


  • Modes: Master, Standalone

Configure StreamMachine's analytics support, which stores data in Elasticsearch.

  • es_uri: Elasticsearch URI. If the URI includes a path (eg http://localhost:9200/sm-prod), the path component will be used to prefix the index names. Otherwise, streammachine will be used as a default.
  • finalize_secs: After how many seconds of inactivity should a session be considered complete and written to the sessions table?


  • Modes: Master (segment_duration), Standalone, Slave (limit_full_index)

Configure HTTP Live Streaming support.

  • segment_duration: What duration (in seconds) should be targeted for HLS segments? Defaults to 10.
  • limit_full_index: Regular expression that should be used to determine whether a full rewind index should be given to a user agent. Undefined by default, which turns the feature off.


  • Modes: Master, Standalone

What duration (in seconds) should be targeted for StreamMachine's internal audio chunking? Defaults to two seconds.


  • Modes: Standalone, Slave

Should StreamMachine look at the X-Forwarded-For header to get connection IP addresses, rather than the actual connecting IP? Defaults to false.


  • Modes: Standalone, Slave

How many slave worker processes should StreamMachine spawn? Defaults to 2. Should typically not be set higher than the number of CPU cores available.


  • Modes: Standalone, Slave

Regular expression that can be used to ban certain user agents from connecting to streams. Defaults to undefined, which turns off the feature.


  • Modes: Master, Standalone, Slave

Valid options are external (default) and internal. If internal, StreamMachine will attempt to spawn its own replacement processes on a SIGUSR2. Running with internal handoffs may complicate process management.


  • Modes: Master, Standalone

Configuration options for the master API.

  • require_auth: Boolean (default false) that governs whether StreamMachine requires authenticated access to the admin API.