Warning!

This page applies to an older version of Orbited (Version 0.5) For info on the current version see the main documentation.


Configuration

  1. Configuration
    1. [global] Section
      1. reactor
      2. echo
      3. proxy
      4. binaryproxy
      5. websocket
      6. dispatch
      7. pid
    2. [listen] Section
    3. [static] Section
    4. [ssl] Section
    5. [access] Section
    6. [logging] Section
    7. [loggers] Section

On Unix systems Orbited looks for a configuration file in /etc/orbited.cfg when started. On windows it looks for "\Program Files\Orbited\etc\orbited.cfg" when started. If neither of these file are found, it will look for orbited.cfg in the directory it is run from. If no configuration file is found, Orbited refuses to start.

Orbited ships with the following example configuration: 

# Example Orbited Configuration file
[global]
#reactor=epoll
#echo.enabled=1
proxy.enabled=1
binaryproxy.enabled=1
#websocket.enabled=1
#dispatch.enabled=1
#dispatch.port=9000

[listen]
http://:8001
# uncomment to enable ssl on port 8043 using given .key and .crt files
#https://:8043
#
#[ssl]
#key=orbited.key
#crt=orbited.crt

[static]
#tmp=/tmp

[access]
irc.freenode.net:6667

[logging]
debug=SCREEN,/var/orbited/debug.log
info=SCREEN,/var/orbited/info.log
access=SCREEN,/var/orbited/info.log
warn=SCREEN,/var/orbited/error.log
error=SCREEN,/var/orbited/error.log

#Don't enable debug by default
enabled.default=info,access,warn,error

# Turn debug on for the "Proxy" logger
[loggers]
Proxy=debug,info,access,warn,error

[global] Section

reactor

By default, orbited uses the "select" reactor; you can choose another with this directive.

For example, in Linux, you can use the "epoll" reactor: 

[global]
reactor=epoll

For more information about reactors consult the Twisted Choosing a Reactor How To.

echo

This is an test protocol that should be disabled.

proxy

Enables the use of the text proxy through the TCPSocket JavaScript object.

binaryproxy

Enables the use of the binary proxy through the BinaryTCPSocket JavaScript object.

websocket

TODO: not sure what is this.

dispatch

To use the legacy OrbitProtocol you need to enable the "dispatch" protocol: 

[global]
dispatch.enabled = 1 # enabled integrations mode
dispatch.port = 9000 # listen for dispatch messages over the Orbit protocol on port 9000

pid

To start multiple instances, specify an unique pid file for each instance: 

[global]
pid.location = /tmp/orbited.pid # lock this file while running to prevent two daemons from starting

[listen] Section

The listen section describes the interfaces and ports Orbited should use to accept browser connections. Each line specifies a protocol, interface, and port in the form of a URI. examples include: 

[listen]
http://:8000 # listen for HTTP on port 80 }}}
https://localhost:443 # listen for https on port 443 on the localhost interface
http://10.0.0.1:80 # listen for HTTP on port 8080 on the interface 10.0.0.1

[static] Section

The static section allows rudimentary configuration for static content. You can configure an arbitrarily named virtual directory under root (You can't use 'static', 'proxy', 'binaryproxy', or 'websocket') to point at an arbitrary on-disk location. You can also set a particular file or directory to serve the as the root content by specifying the named virtual directory INDEX. Here are some examples: 

INDEX=/home/mcarter/website/index.html # will serve the specified "index.html" file as "/"
javascript=/home/mcarter/dev/coolprojects/js # serves .../coolprojects/js/* as /javascript/*

[ssl] Section

In order for listen URIs of the form https:// to work, the ssl section much be present (and python-openssl needs to be installed). This section needs to point to the key and certificate files used for ssl encryption. An example of this configuration is: 

[ssl]
key=/etc/orbited/ssl.key
crt=/etc/orbited/ssl.crt

[access] Section

The access section is where authorization for routing is defined. It is a whitelist that specifies every remote hostname and port that a browser is allowed to connect to through orbited. If a host, port pair doesn't appear in this list, Orbited will not proxy data to that destination. Some examples in this section are: 

[access]
localhost:9998 # Allow connections from the browser to be proxied locally to port 9998. Note that the hostname *must* be "localhost" and not an equivalent like "127.0.0.1"
activemq.domain.com:61613 # Allow STOMP connections to "activemq.domain.com" on port 61613. Note that connections to "domain.com" or "node1.activemq.domain.com" will be rejected.

[logging] Section

The logging section allows you to specify where output to various types of messages go. The message types are:

The output can be sent to multiple files or the screen. Here are some example configurations: 

[logging]
debug=SCREEN # send debug output to the screen
info=SCREEN,/var/log/orbited/info.log # send info output to the screen and the file "/var/log/orbited/info.log"
access=/var/log/orbited/access.log # send access output to the file "/var/log/orbited/access.log"
warn=/var/log/orbited/error.log # send warn output to the file "/var/log/orbited/warn.log"

# send error output to the SCREEN, the file "/var/log/orbited/error.log" and the file "home/mcarter/sever/orbited_error.log"
error=SCREEN,/var/log/orbited/error.log,/home/mcarter/sever/orbited_error.log

NB: Besides SCREEN (aka STDOUT), you can also redirect the output to STDERR. (only available after [357]).

[loggers] Section

this section is used to provide custom logging configuration for individually named logging components in Orbited. For now, this feature is primarily used to provide extensive debugging output to developers. Some of the logging component names include:

While this configuration section can be used to enable output for a particular logging component, the [logging] section still determines where that output goes, rather its the SCREEN or an arbitrary file, or nowhere. An example of enabling debug output for the Proxy code looks like this: 

[loggers]
Proxy=debug,info,access,warn,error # turn all output on for the Proxy component