Go-ethereum: cmd/geth: document the config file

[YihaoPeng]

This is not a bug report, it is just a user feedback. So I didn't use the default issue template.

I am a mining pool operator. I deployed geth for Ethereum mining.

At the beginning, I want to use the configuration file (--config=xxx.toml) of geth.

However, a decision by developers made my plan unsuccessful:

Certain fields have been omitted to prevent sensitive data circulating in configuration files.

So --extradata is omitted... But it is not sensitive at all, it will be public in each block you mined!
And about --mine, it is not considered a configuration item................................................... (https://github.com/ethereum/go-ethereum/issues/17505)

Although very unhappy, I have no choice. I can only switch to using the shell script.

In addition, writing configuration files directly is difficult due to the lack of official documentation.
You can only write the command line options first, then use the dumpconfig command to generate a configuration file.

So why not just use the shell script directly? Although it's not so readable, it has good documentation,
can be written directly, and can controls all the features you want to control.

Let us consider the permutations and combinations in mathematics. There are only three usages for the configuration file of geth:

• Use alone without any command line options: Configuration files can only be generated through command line options with dumpconfig. And some important features cannot be controlled in the configuration file.
• Don't use at all: All features can be controlled through command line options.
• Use with command line options: Why should I choose this? Why do I need a configure file since I must use command line options?

Obviously, the optimal choice is not to use the configuration file at all. This can lead to the conclusion that the current configuration file for geth is basically useless.

However, I still hope to have a normal and convenient configuration file. I just want to a configuration file like Nginx, Bitcoin-core or Parity has. We all know what such a configuration file looks like.

Meme referenced from https://github.com/ethereum/go-ethereum/issues/3332 and it still applies to the status quo.

[sheluchin]

This does seem to be quite a problem. Many tutorials suggest using geth --your-favorite-flags dumpconfig > config.toml, but this lack of consistency and clarity surrounding what is and what isn't included in the configuration file is confusing.

What about a short-term patch that will warn users about unsupported flags when using dumpconfig?

[fjl]

Everything can be configured through command-line flags can also be set using the TOML config file.
But the config file is not documented properly. We will improve documentation of the available options in the geth 1.9 release cycle.

[begetan]

Is there any ongoing work on config documentation?
If not what is the best place and name for that file?

[fjl]

I did some work on it by extending the TOML parser to dump all available config alongside documentation comments. Didn't finish that though.

[agomez314]

Have found the inconsistency of articles online to be frustrating. Really looking forward to having this on the geth documentation as I trust it in having the most up-to-date information. 👍

[garyng2000]

agree with OP, either you give me the toml or don't. At its current form, it is kind of useless(need shell script wrapper then why not just do everything there). This is in addition to the naming convention used is not the same as the command line argument(which at least --help will tell me what they are).

[lichao23]

I did some work on it by extending the TOML parser to dump all available config alongside documentation comments. Didn't finish that though.

@fjl When will it be finished
I am confused about how toml should be configured

[fjl]

Sorry, I didn't get back to it.

[fjl]

Looking at this issue again, I can understand there is a lot of frustration with how the config file works. Let me explain how it works and why it's not the same as the flags:

The geth executable is basically a wrapper around the go-ethereum library, which contains many packages. Each component in go-ethereum has its own little configuration. When setting up everything so that geth can run, we need to translate the meaning of the command line flags into the configuration expected by each component. Sometimes this is straightforward and sometimes it's not.

When we added the config file support, we decided that it would be good to expose the internal configuration structure rather than making a kind of 'flag file' where you just put the command line flags. If you want a flag file, you can always use a shell script to launch geth, so it wouldn't be very useful to have that. Using the config file, you can actually configure things that can't be configured through the flags, because some of the internal components have more options which are not exposed as flags.

However, it seems that this approach is not nice in practice because you have to learn about the internals of go-ethereum to really use the config file properly. I'll eventually put some effort into getting the documentation up, but it's not a big priority right now, sorry.

If you want to check what kind of fields are available in the config, you can also check the GoDoc. For example, here is the configuration of the ethereum protocol: https://pkg.go.dev/github.com/ethereum/go-ethereum/eth#Config. From there, you can explore the config tree by clicking on the types. Let me give an example of using this documentation: if you want to know what can be configured for the miner, click the "miner.Config" link, which is the type of the Miner field of the config. There, you can see that it's possible to configure the ExtraData. To set it in the config file, you need to put the full path to this option (and it has to be written as hex), i.e.

[Eth.Miner]
ExtraData = "0xff"

or

Eth.Miner.ExtraData = "0xff"