Orbited ships with the following example configuration:
# Example Orbited Configuration file
proxy.enabled = 1
session.ping_interval = 40
session.ping_timeout = 30
# uncomment to enable ssl on port 8043 using given .key and .crt files
localhost:8000 -> irc.freenode.net:6667
* -> localhost:4747
#Don't enable debug by default
# Turn debug on for the "Proxy" logger
In general, the listen section describes the interfaces and ports Orbited should bind and listen to. Each line specifies a protocol, interface, and port in the form of a URI. The interface and port tell Orbited _where_ to listen, and the protocol tells it _what_ kind of traffic to expect. There are two basic types of protocols: those that allow a browser to establish a Comet Session, and those that function as standalone servers.
The first category is what Orbited is all about: listening for http and https. Lines beginning with http or https instruct Orbited to listen for http or https connections and proxy those connections in one way or another. This is what enables browsers to connect to the daemon, and Orbited will not work without an http or https line.
A line beginning with some other protocol instructs the daemon to start a certain type of server. This second category is composed of the following options: echo, lineecho, rude, announce, monitor, and stomp. The first four are simple servers that the developer can use to test a deployment or diagnose network problems. A line beginning with stomp:// instructs the Orbited daemon to start the integrated STOMP server, MorbidQ (described in Network setup - STOMP). A line beginning with monitor:// tells Orbited to serve system resource information (available at http://[orbited_interface]:[orbited_port]/system/monitor). Remember: a listen section entry of this type (non-http, non-https) only tells Orbited to listen for a certain type of traffic on a certain port and interface -- a corresponding line in the access section is required for end-users to actually connect.
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
stomp://:61316 # enable MorbidQ and have it listen on port 61613
echo://:8001 # run an echo server on port 8001
monitor://:8005 # provide system information feed on port 8005
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 "/"
More about static files in the "handling static files" 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:
The access section is where authorization for routing is defined. It is a white list 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. Simply put: this is were you define which servers and ports your users will be able to connect to. An entry is necessary for _every_ server your user must access, including non-http, non-https entries in the listen section. Some examples in this section are:
* -> 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:
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)
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:
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"
NB: Besides SCREEN (aka STDOUT), you can also redirect the output to STDERR. (only available after ).
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:
Proxy=debug,info,access,warn,error # turn all output on for the Proxy component