This class abstracts out Tor’s config, and can be used both to create torrc files from nothing and track live configuration of a Tor instance.
Also, it gives easy access to all the configuration options present. This is initialized at “bootstrap” time, providing attribute-based access thereafter. Note that after you set some number of items, you need to do a save() before these are sent to Tor (and then they will be done as one SETCONF).
You may also use this class to construct a configuration from scratch (e.g. to give to
txtorcon.launch_tor()). In this case, values are reflected right away. (If we’re not bootstrapped to a Tor, this is the mode).
Note that you do not need to call save() if you’re just using TorConfig to create a .torrc file or for input to launch_tor().
This class also listens for CONF_CHANGED events to update the cached data in the event other controllers (etc) changed it.
There is a lot of magic attribute stuff going on in here (which might be a bad idea, overall) but the intent is that you can just set Tor options and it will all Just Work. For config items that take multiple values, set that to a list. For example:
conf = TorConfig(...) conf.SOCKSPort = [9050, 1337] conf.HiddenServices.append(HiddenService(...))
(Incoming objects, like lists, are intercepted and wrapped).
FIXME: when is CONF_CHANGED introduced in Tor? Can we do anything like it for prior versions?
- HiddenServiceOptions is special: GETCONF on it returns
several (well, two) values. Besides adding the two keys ‘by hand’ do we need to do anything special? Can’t we just depend on users doing ‘conf.hiddenservicedir = foo’ AND ‘conf.hiddenserviceport = bar’ before a save() ?
- once I determine a value is default, is there any way to actually get what this value is?
This creates and returns a ready-to-go TorConfig instance from the given protocol, which should be an instance of TorControlProtocol.
Current configuration, by keys.
Configuration that has been changed since last save().
Instances of the parser classes, subclasses of TorConfigType
All the names (keys from .parsers) that are a List of something.
returns a Deferred that fires once we’ve set this object up to track the protocol. Fails if we already have a protocol.
return the type of a config key.
Param: name the key
FIXME can we do something more-clever than this for client code to determine what sort of thing a key is?
This only takes args so it can be used as a callback. Don’t pass an arg, it is ignored.
Save any outstanding items. This returns a Deferred which will errback if Tor was unhappy with anything, or callback with this TorConfig object on success.
Returns an iterator of 2-tuples (config_name, value), one for each configuration option in this config. This is more-or-less and internal method, but see, e.g., launch_tor()’s implementation if you thing you need to use this for something.
txtorcon.TorConfig.create_torrc()which returns a string which is also a valid