Configuration

  1. Configuration
    1. [global] Section
      1. reactor
      2. proxy
      3. 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. You can also manually specify the location of the configuration file with the --config option. If no configuration file is found, Orbited refuses to start.

Orbited ships with the following example configuration: 

# Example Orbited Configuration file

[global]
reactor=select
# reactor=kqueue
# reactor=epoll
proxy.enabled = 1
session.ping_interval = 40
session.ping_timeout = 30

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

[static]

[access]
localhost:8000 -> irc.freenode.net:6667

[logging]
debug=STDERR,debug.log
info=STDERR,info.log
access=STDERR,info.log
warn=STDERR,error.log
error=STDERR,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. Select will work on all platforms and is the only option on Windows, but has scalability issues. On Linux you should choose "epoll" and on OS X/FreeBSD you should choose "kqueue".

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

proxy

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

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 8000 }}}
https://localhost:443 # listen for https on port 443 on the localhost interface
http://10.0.0.1:80 # listen for HTTP on port 80 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.

Note that the above examples both use the left-hand side (LHS) rule of "*". The LHS of each access rule refers to the HTTP Host header value that is allowed. For instance, If I were to visit http://orbited.org:8000/static/demos/chat, then my browser would send the host header "orbited.org:8000". Therefore, I need to have an LHS value of "orbited.org:8000". Of course, the wildcard "*" would work as well. The reason for this rule is to allow you to protect against variants of the Princeton attack. It's a good idea to use '*' when developing, but once you know the hostname and port that you are going to use for deployment, put those in as the LHS. Some examples: 

[access]
localhost -> irc.freenode.net # allow access with hostname localhost (implied port 80) to make proxy requests to irc.freenode.net
orbited.org:8000 -> localhost:61613 # allow access with hostname orbited.org:8000 to make proxy requests to localhost:61613 (local activemq server)

[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, whether 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