-
Notifications
You must be signed in to change notification settings - Fork 42
Upgrade Guide from version 21.1.0 (or older) to a newer release
relayor users using version 21.1.0 or older should carefully read this page before upgrading to a newer version, because this transition might require some manual steps. A new feature (dynamically support torrc options) required a backwards incompatible change.
Manual steps are required to prevent known issues but the manual steps are limited to the control node (variable renaming) and no actions are required on the tor relays themselves.
Before starting the upgrade we recommend to run your playbook in its current state with the old relayor version once again before upgrading to ensure your systems are in a consistent state with your current configuration before upgrading.
If you use any of these variables you need to use their new variable naming, if you do not use any of these variables no actions are required.
- tor_Sandbox
- tor_NoExec
- tor_additional_MyFamily
- tor_DirPortFrontPage
- tor_PublishServerDescriptor
- tor_DirPortFrontPage
- tor_PublishServerDescriptor
- tor_DisableNetwork
- tor_HeartbeatPeriod
- tor_SafeLogging
- tor_MaxAdvertisedBandwidth
- tor_PerConnBWRate
- tor_PerConnBWBurst
- tor_ConnLimit
- tor_CellStatistics
- tor_EntryStatistics
- tor_ExitPortStatistics
- tor_DirReqStatistics
- tor_ConnDirectionStatistics
- tor_HiddenServiceStatistics
- tor_ExtraInfoStatistics
- tor_MaxOnionQueueDelay
- tor_NumCPUs
- tor_PortForwarding
- tor_AccountingMax
- tor_AccountingRule
- tor_AccountingStart
- tor_MaxMemInQueues
- tor_ExtendAllowPrivateAddresses
- tor_DirPolicy
- tor_DirCache
- tor_ConstrainedSockets
- tor_ConstrainedSockSize
- tor_DisableAllSwap
- tor_DisableDebuggerAttachment
- tor_KeepalivePeriod
- tor_ProtocolWarnings
- tor_LogTimeGranularity
- tor_KeepBindCapabilities
- tor_HardwareAccel
- tor_AccelName
- tor_AccelDir
- tor_AvoidDiskWrites
- tor_ExitPolicyRejectPrivate
- tor_PortForwardingHelper
- tor_RefuseUnknownExits
- tor_ServerDNSResolvConfFile
- tor_ServerDNSAllowBrokenConfig
- tor_ServerDNSSearchDomains
- tor_ServerDNSDetectHijacking
- tor_ServerDNSTestAddresses
- tor_ServerDNSAllowNonRFC953Hostnames
- tor_ServerDNSRandomizeCase
- tor_GeoIPFile
- tor_GeoIPv6File
- tor_TLSECGroup
- tor_ShutdownWaitLength
- tor_DoSCircuitCreationEnabled
- tor_DoSCircuitCreationMinConnections
- tor_DoSCircuitCreationRate
- tor_DoSCircuitCreationBurst
- tor_DoSCircuitCreationDefenseType
- tor_DoSCircuitCreationDefenseTimePeriod
- tor_DoSConnectionEnabled
- tor_DoSConnectionMaxConcurrentCount
- tor_DoSConnectionDefenseType
- tor_DoSRefuseSingleHopClientRendezvous
If you used any of these variables you need to convert them into the new form as a dictionary member of the tor_config dictionary without the tor_ prefix.
example usage of variables:
tor_signingkeylifetime_days: 20
tor_Sandbox: 0
tor_NoExec: 0
Starting with version 21.2.0 most torrc options are set in the tor_config dictionary.
The following options can NOT be set in tor_config:
-
OfflineMasterKey,RunAsDaemon,Log,SocksPort,SigningKeyLifetime,OutboundBindAddress,User,DataDirectory,ORPort,OutboundBindAddress,OutboundBindAddressExit,DirPort,SyslogIdentityTag,PidFile,MetricsPort,MetricsPortPolicy,ControlSocket,CookieAuthentication,Nickname,ExitRelay,IPv6Exit,ExitPolicy,RelayBandwidthRate,RelayBandwidthBurst
because there are other variables (see the README) that indirectly or directly set their value.
Starting with version 21.2.0-alpha the above example would look like this:
tor_signingkeylifetime_days: 20
tor_config:
Sandbox: 0
NoExec: 0
After changing your variables to the new format we recommend to run ansible-playbook in diff mode -D and look for any unexpected changes in the diff output.
It is expected that the torrc configuration files changes (some config options get reordered), but the configuration content should not change semantically.