mirrors/electrs
1
0
Fork 0
mirror of https://github.com/romanz/electrs.git synced 2025-02-22 22:36:37 +01:00
Code Issues Projects Releases Wiki Activity

Added in-depth explanation of cookie deprecation

Browse source 
This adds more informtion about cookie deprecation, especially
motivation, so the users won't be frustrated because of unexplained
change. It also removes a warning that's no longer applicable.
This commit is contained in:
Martin Habovstiak 2021-02-22 19:52:40 +01:00
parent d114a6b4a7
commit afe32bb5b7
2 changed files with 34 additions and 2 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

33
doc/cookie_deprecation.md Normal file
View file

@ -0,0 +1,33 @@
# Deprecation of cookie option
## What?
As of 0.8.8 the `cookie` option is deprecated and it will be removed.
A new `auth` option was added.
If you don't use the `cookie` otpion, you're not affected and don't need to read this.
Note that this is different from `cookie_file`.
## Why?
The option was confusing:
* If you entered the path to cookie file (usually `~/.bitcoin/.cookie`), it wouldn't work.
* If you copied the contents of cookie file into it, `electrs` would break at the next restart of the system.
* If you used a script to fix the above run before `electrs` starts, it'd still break if `bitcoind` restarted for any reason.
* If you used `BindsTo` option of systemd, you'd solve the issue but introduce needless downtime and waste of performance.
* Entering `username:password` was the only valid use of `cookie` but it had nothing to do with cookie.
## What to do?
If you're installing `electrs` for the first time, just don't use `cookie`.
If you're updating, reconsider the motivation above.
If you used copying script, just use `cookie_file` to get the cookie directly.
If you also used `BindsTo`, we recommend removing it.
If you used fixed username and password because you didn't know about cookie or did it before `cookie_file` was implemented, reconsider using cookie authentication.
If you really have to use fixed username and password, specify them using `auth` option (`username:password` like before) and remove the `cookie` option.
## When the option will be removed?
Probably in a few months.
It'll still be detected and turned into explicit error for a while to make sure people really see the message and know what's going on.
You can see [the tracking issue #371](https://github.com/romanz/electrs/issues/371) to monitor the progress of the change.

3
doc/usage.md
View file

@ -219,8 +219,6 @@ You need to use a number in config file if you want to increase verbosity (e.g.
**Authentication**
**Warning:** If you're reading this before version 0.8.8 exists either use `cookie_file` or check the version of documentation before this line was committed.
In addition, config files support `auth` option to specify username and password.
This is not available using command line or environment variables for security reasons (other applications could read it otherwise).
**Important note**: `auth` is different from `cookie_file`, which points to a file containing the cookie instead of being the cookie itself!
@ -449,6 +447,7 @@ $ ./contrib/addr.py 144STc7gcb9XCp6t4hvrcUEKg9KemivsCR # sample address from bl
> It's strongly recommended to use proper cookie authentication using `cookie_file`.
> If you really have to use fixed username and password, explicitly specified in `bitcoind` config, use `auth` option instead.
> Users of `btc-rpc-proxy` using `public:public` need to use `auth` too.
> You can read [a detailed explanation of cookie deprecation with motivation explained](cookie_deprecation.md).
As with any other application, you need to remember how you installed `electrs` to upgrade it.
If you don't then here's a little help: run `which electrs` and compare the output