Opened 4 years ago

Last modified 11 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:

Description

Perennial request

Some attempts and proposals:

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 (add)

Attachments (1)

config.diff (5.3 KB) - added by zzz 3 years ago.
prelim. patch for review

Download all attachments as: .zip

Change History (10)

comment:1 Changed 4 years ago by zzz

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
Last edited 4 years ago by zzz (previous) (diff)

comment:2 Changed 4 years ago by zzz

  • 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
Last edited 4 years ago by zzz (previous) (diff)

comment:3 Changed 4 years ago by zzz

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 in reply to: ↑ description Changed 4 years ago by str4d

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: Changed 4 years ago by zzz

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 in reply to: ↑ 5 Changed 4 years ago by str4d

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=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.

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 3 years ago by str4d

  • Status changed from new to open

Changed 3 years ago by zzz

prelim. patch for review

comment:8 Changed 3 years ago by zzz

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 11 months ago by zzz

  • Cc slumlord added
  • Owner set to sadie
  • Status changed from open to assigned

reassigning to sadie for guidance and priority setting
cc: slumlord

Note: See TracTickets for help on using tickets.