Opened 4 years ago
Last modified 18 months ago
#1677 assigned task
Document all options
| Reported by: | zzz | Owned by: | sadie |
|---|---|---|---|
| Priority: | minor | Milestone: | eventually |
| Component: | www/i2p | Version: | 0.9.22 |
| Keywords: | docs | Cc: | slumlord |
| Parent Tickets: | Sensitive: | no |
Description
Perennial request
Some attempts and proposals:
- http://echelon.i2p/docs/advanced.options.txt
- Similar effort for rate stats: http://i2p-projekt.i2p/en/misc/ratestats
- str4d proposed extending Properties and our utils to preserve comment lines when reading/saving, sounds hard
- We could pull them out of the javadocs somehow
My theory was always that you don't need a list, you should just find the docs for what you want to do, but everybody loves a list.
However we format the results, first we need the descriptions for each.
See below for my list.
Subtickets
Attachments (1)
Change History (10)
comment:2 Changed 4 years ago by
| Keywords: | docs added |
|---|
And the output:
crypto.dh.precalc.delay crypto.dh.precalc.max crypto.dh.precalc.min crypto.elGamal.useLongKey crypto.lowTagThreshold crypto.tagsToSend crypto.yk.precalc.delay crypto.yk.precalc.max crypto.yk.precalc.min geoip.dir i2cp.accessList i2cp.auth i2cp.destination.sigType i2cp.disableInterface i2cp.domainSocket i2cp.dontPublishLeaseSet i2cp.enableAccessList i2cp.enableBlackList i2cp.fastReceive i2cp.hostname i2cp.keyPassword i2cp.keystorePassword i2cp.maxSessions i2cp.messageReliability i2cp.outboundBytesPerSecond i2cp.password i2cp.port i2cp.SSL i2cp.strictAuth i2cp.tcp.host i2cp.tcp.port i2cp.username i2np.bandwidth.inboundBurstKBytes i2np.bandwidth.inboundBurstKBytesPerSecond i2np.bandwidth.inboundKBytesPerSecond i2np.bandwidth.outboundBurstKBytes i2np.bandwidth.outboundBurstKBytesPerSecond i2np.bandwidth.outboundKBytesPerSecond i2np.disable i2np.ipv4.firewalled i2np.laptopMode i2np.lastCountry i2np.lastIP i2np.lastIPChange i2np.ntcp.autoip i2np.ntcp.autoport i2np.ntcp.bindInterface i2np.ntcp.enable i2np.ntcp.hostname i2np.ntcp.port i2np.ntcp.useDirectBuffers i2np.udp.addressSources i2np.udp.allowDirect i2np.udp.bindInterface i2np.udp.enable i2np.udp.fixedPort i2np.udp.forceIntroducers i2np.udp.host i2np.udp.internalPort i2np.udp.maxConcurrentEstablish i2np.udp.maxPort i2np.udp.minPort i2np.udp.mtu i2np.udp.padding i2np.udp.port i2np.udp.preferred i2np.udp.status i2np.upnp.enable i2np.upnp.HTTPPort i2np.upnp.ignore i2np.upnp.SSDPPort i2p.dir.base i2p.dir.config i2p.disableSSLHostnameVerification i2p.hostsfilelist i2p.nameservicelist i2p.naming.blockfile.writeInAppContext i2p.naming.eepget.list i2p.naming.hostsTxt.useB32 i2p.naming.impl i2p.reseedURL i2p.streaming.answerPings i2p.streaming.blacklist i2p.streaming.bufferSize i2p.streaming.congestionAvoidanceGrowthRateFactor i2p.streaming.connectDelay i2p.streaming.connectTimeout i2p.streaming.disableRejectLogging i2p.streaming.dsalist i2p.streaming.enforceProtocol i2p.streaming.inactivityAction i2p.streaming.inactivityTimeout i2p.streaming.initialAckDelay i2p.streaming.initialReceiveWindow i2p.streaming.initialResendDelay i2p.streaming.initialRTO i2p.streaming.initialWindowSize i2p.streaming.manager i2p.streaming.maxConcurrentStreams i2p.streaming.maxConnsPerDay i2p.streaming.maxConnsPerHour i2p.streaming.maxConnsPerMinute i2p.streaming.maxMessageSize i2p.streaming.maxResends i2p.streaming.maxTotalConnsPerDay i2p.streaming.maxTotalConnsPerHour i2p.streaming.maxTotalConnsPerMinute i2p.streaming.maxWindowSize i2p.streaming.pcap i2p.streaming.profile i2p.streaming.readTimeout i2p.streaming.slowStartGrowthRateFactor i2p.streaming.writeTimeout jbigi.loadedResource logger.consoleBufferSize logger.dateFormat logger.defaultLevel logger.displayOnScreen logger.dropDuplicates logger.dropOnOverflow logger.flushInterval logger.format logger.logBufferSize logger.logFileName logger.logFileSize logger.logRotationLimit logger.minimumOnScreenLevel logger.record. profileOrganizer.minFastPeers profileOrganizer.minHighCapacityPeers profileOrganizer.sameCountryBonus router.batchFrequency router.blocklist.detail router.blocklist.enable router.blocklist.file router.clientConfigFile router.configLocation routerconsole.advanced routerconsole.allowUntrustedPlugins routerconsole.auth. routerconsole.auth.enable routerconsole.country routerconsole.disableXFrame routerconsole.enableClientChange routerconsole.enablePluginInstall routerconsole.favorites routerconsole.forceMobileConsole routerconsole.geoip.enable routerconsole.graphEvents routerconsole.graphPeriods routerconsole.graphPersistent routerconsole.graphRefresh routerconsole.graphX routerconsole.graphY routerconsole.keyPassword routerconsole.keystorePassword routerconsole.lang routerconsole.newsLastChecked routerconsole.newsLastHidden routerconsole.newsLastUpdated routerconsole.newsTranslate routerconsole.oldHomePage routerconsole.passwordManager.migrated routerconsole.searchEngine routerconsole.searchEngines routerconsole.services routerconsole.showSearch routerconsole.summaryBar. routerconsole.summaryDisableRefresh routerconsole.summaryRefresh routerconsole.theme routerconsole.theme. routerconsole.universal.theme router.defaultProcessingTimeThrottle router.disableDecayingBloomFilter router.dispatchThreaded router.dynamicKeys router.encryptRouterLookups router.fetchNewsThroughProxy router.floodfillParticipant router.forceBandwidthClass router.forceDecayingBloomFilter router.forceUnreachable router.gracefulHUP router.hiddenMode router.historyFilename router.inboundClientExcludeSlow router.inboundClientExcludeUnreachable router.inboundClientExcludeUptime router.inboundExploratoryExcludeSlow router.inboundExploratoryExcludeUnreachable router.inboundExploratoryExcludeUptime router.isHidden router.jobLagFatal router.jobLagWarning router.jobRunFatal router.jobRunWarning router.jobWarmupTime router.keepHistory router.keyBackupDir router.keyring.key. router.maxJobRunners router.maxParticipatingTunnels router.maxWaitingJobs router.networkDatabase.dbDir router.networkDatabase.flat router.newsRefreshFrequency router.newsURL router.outboundClientExcludeSlow router.outboundClientExcludeUnreachable router.outboundClientExcludeUptime router.outboundExploratoryExcludeSlow router.outboundExploratoryExcludeUnreachable router.outboundExploratoryExcludeUptime router.passwordManager.migrated router.profileDir router.publishPeerRankings router.publishUnreachableRouters router.rejectStartupTime router.reseedDisable router.reseedProxy.authEnable router.reseedProxyEnable router.reseedProxyHost router.reseedProxy.password router.reseedProxyPort router.reseedProxy.username router.reseedSSLDisable router.reseedSSLProxy.authEnable router.reseedSSLProxyEnable router.reseedSSLProxyHost router.reseedSSLProxy.password router.reseedSSLProxyPort router.reseedSSLProxy.username router.reseedSSLRequired router.sharePercentage router.sigType router.trustedLinks router.trustedUpdateKeys router.updateDevSU3 router.updateDevSU3Available router.updateDevSU3URL router.updateDisabled router.updateLastDownloaded router.updatePolicy router.updateProxyHost router.updateProxyPort router.updateThroughProxy router.updateUnsigned router.updateUnsignedAvailable router.updateUnsignedURL router.updateURL router.variableLeaseExpiration router.verifyRouterInfoStore stat.full stat.logFile stat.logFilters time.concurringServers time.disabled time.disableOffset time.queryFrequencyMs time.sntpServerList wrapper.logfile
comment:3 Changed 4 years ago by
Note that the general config file format, and some files (clients.config, logger.config, i2ptunnel.config) are documented here:
http://i2p-projekt.i2p/en/docs/spec/configuration
Any router.config documentation should be linked from there.
comment:4 Changed 4 years ago by
Replying to zzz:
- str4d proposed extending Properties and our utils to preserve comment lines when reading/saving, sounds hard
I found this nice implementation: http://www.dreamincode.net/forums/topic/53734-java-code-to-modify-properties-file-and-preserve-comments/page__p__874511&#entry874511
It wouldn't be directly usable, but could be adapted for our needs. Supporting persistent comments in router.config would require modifications to DataHelper.loadProps() and DataHelper.saveProps(), and Router would need to store a CommentedProperties that could be updated on save instead of dynamically generating an OrderedProperties. (This could be done by overriding putAll to check if a property already exists, and if not then add it as a new line at the end of the file, possibly with a descriptive comment.)
My theory was always that you don't need a list, you should just find the docs for what you want to do, but everybody loves a list.
Docs can be hard to find, if you don't know what to search for. The prevalence of documentation in config files also means that many server ops look there first for common settings. More than that, server ops (at least those I have talked to about I2P's config) like being able to format their config file how they want, and have it stay that way.
If config files did support comments and kept their state, then we could have the installer include a default router.config with common options and their documentation. We should still have all options documented on the website, however.
comment:5 follow-up: 6 Changed 4 years ago by
Not too impressed with that code, except perhaps as inspiration. (Vector? ick)
We can, of course, include a default router.config with documentation, whether or not we do anything else. Without comment-preserving code, the comments wouldn't survive in the .i2p file but they would be found in the $I2P (i.e. reference) file.
Another alternative:
We don't preserve comments in the config file, but we do have a hardcoded table (or descriptor file) of descriptions for each key. When writing out the file, we just spit out any description we find for a key as a comment line before we write out the key. Then spit out all the other descriptions at the end.
This doesn't preserve user-generated comments, but maybe that's not so important.
As you noted above, Router doesn't even save the Properties returned from DataHelper?.loadProps() (see readConfig()), because a ConcurrentHashMap? is so much nicer than an unsynchronized Properties to store things in.
One problem that all of these solutions have is that you want to bind comments to a key=value line, so they live and die together. But that fails with a comment style like:
# this is the foo setting, default is false, uncomment and change to true to enable # foo=false # this is the bar setting, default is false, uncomment and change to true to enable # bar=false # this is the baz setting, default is false, uncomment and change to true to enable baz=true
But if we uncomment the 'foo=false' line in the default config file, then we can't change the default in our code, so that's bad too.
Keeping all the comments in memory also sounds icky. Maybe just a read-before-write is sufficient, to store the comments only briefly.
Not yet convinced a coding solution is necessary or cleanly doable.
comment:6 Changed 4 years ago by
Replying to zzz:
Not too impressed with that code, except perhaps as inspiration. (Vector? ick)
It was written for Java 1.4 :P The original author did say he would implement it differently now.
We can, of course, include a default router.config with documentation, whether or not we do anything else. Without comment-preserving code, the comments wouldn't survive in the .i2p file but they would be found in the $I2P (i.e. reference) file.
Another alternative:
We don't preserve comments in the config file, but we do have a hardcoded table (or descriptor file) of descriptions for each key. When writing out the file, we just spit out any description we find for a key as a comment line before we write out the key. Then spit out all the other descriptions at the end.
This doesn't preserve user-generated comments, but maybe that's not so important.
It would be an improvement, at least.
As you noted above, Router doesn't even save the Properties returned from DataHelper?.loadProps() (see readConfig()), because a ConcurrentHashMap? is so much nicer than an unsynchronized Properties to store things in.
One problem that all of these solutions have is that you want to bind comments to a key=value line, so they live and die together. But that fails with a comment style like:
# this is the foo setting, default is false, uncomment and change to true to enable # foo=false # this is the bar setting, default is false, uncomment and change to true to enable # bar=false # this is the baz setting, default is false, uncomment and change to true to enable baz=trueBut if we uncomment the 'foo=false' line in the default config file, then we can't change the default in our code, so that's bad too.
Easy enough: define #foo=bar explicitly as a commented-out parameter, and # foo... as a real comment (which is in keeping with many other config file conventions). Then the reader can look for commented-out parameters and uncomment them when settings are changed in the routerconsole.
Keeping all the comments in memory also sounds icky. Maybe just a read-before-write is sufficient, to store the comments only briefly.
Not yet convinced a coding solution is necessary or cleanly doable.
Another alternative would be to leverage Commons Configuration, a self-contained 360kB JAR that would handle all of the above issues for us with a `Properties`-like object. It unfortunately can't be cast to a Properties, but for router.config the router converts to a Map anyway, so you'd just do the same here.
If we wanted to use Commons Configuration in other config files, more extensive patching would be necessary to convert from PropertiesConfiguration to Properties, but not unreasonable.
comment:7 Changed 4 years ago by
| Status: | new → open |
|---|
comment:8 Changed 3 years ago by
Attached patch takes a config file of descriptions, and merges it with the config when writing out. Not coded: merging for display on /configadvanced. This is rougly the 'alternative' proposed in comment 5 above.
Sample line from router.help.config:
crypto.elGamal.useLongKey=Use a long private key for ElGamal?\ntrue/false, default true on most platforms
Sample lines from router.config after a save:
# # Use a long private key for ElGamal? # true/false, default true on most platforms # crypto.elGamal.useLongKey=true
This solution does not preserve comments when reading in a config file. They are remerged from the router.help.config file on every write.
Not sure how much I like this solution, so posting for discussion.
comment:9 Changed 18 months ago by
| Cc: | slumlord added |
|---|---|
| Owner: | set to sadie |
| Status: | open → assigned |
reassigning to sadie for guidance and priority setting
cc: slumlord
My list generator for core, router, console, and streaming. I2PTunnel not included, those generally don't apply to router.config. The list is pretty good, but it misses anything not declared as PROP_foo.
find \ ./router/java/src/net/i2p/ ./core/java/src/ ./apps/streaming/java/src/net/i2p ./apps/ministreaming/java/src/net/i2p ./apps/routerconsole/java/src/net/i2p/ \ -type f -name \*.java -exec grep PROP_ {} \; | \ grep static | \ grep -v // | \ cut -f 2 -d '=' | \ cut -f 2 -d '"' | \ grep '\.' | \ grep -v PROP_ | \ grep -v '^\.' | \ sort | \ uniq