doc: Add documentation for the new whitelist permissions #16629

pull NicolasDorier wants to merge 1 commits into bitcoin:master from NicolasDorier:doc/permissions changing 1 files +13 −5
  1. NicolasDorier commented at 4:43 am on August 16, 2019: contributor
    Documenting the new feature #16248 . Ping Sjors .
  2. fanquake added the label Docs on Aug 16, 2019
  3. DrahtBot commented at 5:32 am on August 16, 2019: member

    The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

    Conflicts

    No conflicts as of last run.

  4. fanquake renamed this:
    [Doc] Add documentation for the new whitelist permissions
    doc: Add documentation for the new whitelist permissions
    on Aug 16, 2019
  5. fanquake added this to the milestone 0.19.0 on Aug 16, 2019
  6. Sjors commented at 8:07 am on August 16, 2019: member
    @NicolasDorier can you include my “inbound” clarification from #16555 so I can close that?
  7. in src/init.cpp:442 in 42bc1eb4c4 outdated 
    437@@ -438,8 +438,8 @@ void SetupServerArgs()
438 #else
439     hidden_args.emplace_back("-upnp");
440 #endif
441-    gArgs.AddArg("-whitebind=<addr>", "Bind to given address and whitelist peers connecting to it. Use [host]:port notation for IPv6", ArgsManager::ALLOW_ANY, OptionsCategory::CONNECTION);
442-    gArgs.AddArg("-whitelist=<IP address or network>", "Whitelist peers connecting from the given IP address (e.g. 1.2.3.4) or CIDR notated network (e.g. 1.2.3.0/24). Can be specified multiple times."
443+    gArgs.AddArg("-whitebind=<[(permissions,)*@]addr>", "Bind to given address and whitelist peers connecting to it. Use [host]:port notation for IPv6.  Available permissions are: 'forcerelay,relay,noban,mempool,bloomfilter'. If the permission marker '@' is not specified, it will default to 'noban,mempool' with `whitelistrelay` and `whitelistforcerelay` optionally adding 'relay' and 'forcerelay' respectively. Can be specified multiple times.", ArgsManager::ALLOW_ANY, OptionsCategory::CONNECTION);
444+    gArgs.AddArg("-whitelist=<[(permissions,)*@]IP address or network>", "Whitelist peers connecting from the given IP address (e.g. 1.2.3.4) or CIDR notated network (e.g. 1.2.3.0/24). Available permissions are: 'forcerelay,relay,noban,mempool,bloomfilter'. If the permission marker '@' is not specified, it will default to 'noban,mempool' with `whitelistrelay` and `whitelistforcerelay` optionally adding 'relay' and 'forcerelay' respectively. Can be specified multiple times."
    Sjors commented at 8:12 am on August 16, 2019:

    whitelistrelay is true by default, whereas whitelistforcerelay defaults to false, so a better wording would be:

    0If the permission marker '@' is not specified, it will default to 
1'noban,mempool,whitelistrelay', unless `-whitelistrelay=0`.
2 If `-whitelistforcerelay=1` then 'forcerelay' is also set by default.
    MarcoFalke commented at 1:06 pm on August 16, 2019:

    Would it be possible to factor out the string with the list of permissions to a single symbol (mabye in net_permissions.h?) Can you split the cpp string literal into muliple lines?

    0   "safd1. "
1   "foo2. "
2   "foobar3. (default...)"
    NicolasDorier commented at 3:46 pm on August 16, 2019:
    Will do after #16555 get merged.
  8. NicolasDorier commented at 8:19 am on August 16, 2019: contributor
    @Sjors let’s merge yours first.
  9. DrahtBot added the label Needs rebase on Aug 19, 2019
  10. NicolasDorier commented at 4:07 am on August 20, 2019: contributor 
     0
 1  -whitebind=<[(permissions,)*@]addr>
 2       Bind to given address and whitelist peers connecting to it. Use
 3       [host]:port notation for IPv6. If the permission marker '@' is
 4       specified, you can add a comma separated list of the following
 5       available permissions 'bloomfilter, noban, forcerelay, relay,
 6       mempool'. If the permission marker '@' is not specified, it will
 7       default to 'noban,mempool' with `whitelistrelay` and
 8       `whitelistforcerelay` optionally adding 'relay' and 'forcerelay'
 9       respectively. Can be specified multiple times.
10
11  -whitelist=<[(permissions,)*@]IP address or network>
12       Whitelist peers connecting from the given IP address (e.g. 1.2.3.4) or
13       CIDR notated network (e.g. 1.2.3.0/24). If the permission marker
14       '@' is specified, you can add a comma separated list of the
15       following available permissions 'bloomfilter, noban, forcerelay,
16       relay, mempool'. If the permission marker '@' is not specified,
17       it will default to 'noban,mempool' with `whitelistrelay` and
18       `whitelistforcerelay` optionally adding 'relay' and 'forcerelay'
19       respectively. Can be specified multiple times.
20
21  -whitelistforcerelay
22       Force relay of transactions from whitelisted inbound peers even if the
23       transactions were already in the mempool or violate local relay
24       policy, this parameter is ignored if specific permissions are
25       applied via whitebind/whitelist (default: 0)
26
27  -whitelistrelay
28       Accept relayed transactions received from whitelisted inbound peers even
29       when not relaying transactions, this parameter is ignored if
30       specific permissions are applied via whitebind/whitelist
31       (default: 1)
  11. NicolasDorier force-pushed on Aug 20, 2019
  12. NicolasDorier commented at 4:09 am on August 20, 2019: contributor
    @MarcoFalke instead of using constant, I built in during runtime, it makes sure that the documentation is updated if the list of permission is updated.
  13. DrahtBot removed the label Needs rebase on Aug 20, 2019
  14. in src/init.cpp:445 in 38aeb4d3af outdated 
    443-        " Whitelisted peers cannot be DoS banned", ArgsManager::ALLOW_ANY, OptionsCategory::CONNECTION);
444+    std::string permissionsDoc = "";
445+    for (const auto& permission : NetPermissions::ToStrings(PF_ALL)) {
446+        permissionsDoc = strprintf("%s, %s", permissionsDoc, permission);
447+    }
448+    permissionsDoc = permissionsDoc.substr(2); // remove starting " ,"
    MarcoFalke commented at 6:58 pm on August 20, 2019:
    This code should live in the net_permissions module
    NicolasDorier commented at 5:55 am on August 22, 2019:
    Why? This is the only place it is needed.
  15. harding commented at 0:55 am on August 21, 2019: contributor

    @NicolasDorier I think this could be a bit more concise. If possible, it’d also be good if it could briefly describe what the various options meant (even I had to look at the code to figure out what mempool provide, although BIP35 support was one of my guesses). Here’s a suggestion for white(bind|list), the other two looked ok to me:

     0  -whitebind=<[(permissions,)*@]addr>
 1       Bind to given address and whitelist peers connecting to it. Use
 2       [host]:port notation for IPv6.  Allowed permissions are
 3       bloomfilter (allow requesting BIP37 filtered blocks and
 4       transactions), noban (do not ban for misbehavior), forcerelay
 5       (relay even non-standard transactions), relay (relay even in
 6       -blocksonly mode), and mempool (allow requesting BIP35 mempool
 7       contents).  Specify multiple permissions separated by commas
 8       (default: noban,mempool).  Can be specified multiple times
 9
10  -whitelist=<[(permissions,)*@]IP address or network>
11       Whitelist peers connecting from the given IP address (e.g. 1.2.3.4) or
12       CIDR notated network (e.g. 1.2.3.0/24).  Uses same permissions as
13       -whitebind.  Can be specified multiple times
  16. MarcoFalke referenced this in commit 52b9797119 on Aug 22, 2019
  17. NicolasDorier commented at 4:09 pm on August 22, 2019: contributor
    @harding I like it, @MarcoFalke it means that we won’t need your new string join util. :( Will rebase tomorrow.
  18. MarcoFalke commented at 4:28 pm on August 22, 2019: member

    @MarcoFalke it means that we won’t need your new string join util. :(

    Good to hear. I like the new text as well. Will take a closer look in a couple of days.

  19. NicolasDorier force-pushed on Aug 23, 2019
  20. NicolasDorier commented at 4:34 am on August 23, 2019: contributor
    I just updated to use @harding suggestion, added documentation for bloomfilter permission as well. I needed to change the doc for -whitelistforcerelay and -whitelistrelay as well.
  21. NicolasDorier commented at 4:39 am on August 23, 2019: contributor
    the linter says whitebind is undocumented?
  22. NicolasDorier force-pushed on Aug 23, 2019
  23. harding commented at 5:01 am on August 23, 2019: contributor
    @NicolasDorier bloomfilter was in my description so now you have it twice. :-)
  24. sidhujag referenced this in commit 6745db91ae on Aug 23, 2019
  25. NicolasDorier force-pushed on Aug 23, 2019
  26. NicolasDorier commented at 9:38 am on August 23, 2019: contributor
    oops, fixed it.
  27. NicolasDorier commented at 9:51 am on August 23, 2019: contributor
    Ok somehow this break the tests oO checking what happen.
  28. NicolasDorier force-pushed on Aug 23, 2019
  29. Sjors commented at 10:45 am on August 23, 2019: member

    ACK d536a10

    Nit: remove spaces in examples default: noban,mempool,relay and 1.2.3.0/24.

  30. meshcollider referenced this in commit 910ff94cf5 on Aug 24, 2019
  31. NicolasDorier force-pushed on Aug 24, 2019
  32. NicolasDorier force-pushed on Aug 24, 2019
  33. NicolasDorier commented at 4:01 am on August 24, 2019: contributor
    Indeed, removed the spaces. Should be ready now.
  34. NicolasDorier commented at 2:17 pm on August 24, 2019: contributor
    I broke the tests again. This is the hardest PR doc I did in my life.
  35. [Doc] Add documentation for the new whitelist permissions 66ad75472f
  36. NicolasDorier force-pushed on Aug 24, 2019
  37. NicolasDorier commented at 2:45 pm on August 24, 2019: contributor
    I rebased, now the error rpc_invalidateblock does not seem related to this PR.
  38. MarcoFalke commented at 2:53 pm on August 24, 2019: member
    That is a known bug. See #16444. You don’t need a passing travis on a doc-commit, it can be merged in any case after review.
  39. sidhujag referenced this in commit 2eb0fa935a on Aug 25, 2019
  40. NicolasDorier commented at 7:26 am on August 26, 2019: contributor
    I think this one is ready to be merged @MarcoFalke
  41. Sjors commented at 10:23 am on August 26, 2019: member
    Indeed, re-ACK 66ad75472
  42. MarcoFalke referenced this in commit adff8fe321 on Aug 26, 2019
  43. MarcoFalke merged this on Aug 26, 2019
  44. MarcoFalke closed this on Aug 26, 2019
  45. sidhujag referenced this in commit e1511ab3e2 on Aug 27, 2019
  46. ShengguangXiao referenced this in commit 8f8ea9b770 on Aug 28, 2020
  47. jasonbcox referenced this in commit fdedc9312f on Oct 19, 2020
  48. vijaydasmp referenced this in commit 618c33a003 on Oct 29, 2021
  49. vijaydasmp referenced this in commit 1a49e1acda on Oct 30, 2021
  50. vijaydasmp referenced this in commit e4613be9b0 on Nov 2, 2021
  51. vijaydasmp referenced this in commit 134e34b047 on Nov 7, 2021
  52. vijaydasmp referenced this in commit 27cea1e1b0 on Nov 7, 2021
  53. vijaydasmp referenced this in commit 9cebffd361 on Nov 11, 2021
  54. vijaydasmp referenced this in commit 18f6498700 on Nov 12, 2021
  55. vijaydasmp referenced this in commit f6a715a982 on Nov 13, 2021
  56. vijaydasmp referenced this in commit 94739a8d51 on Nov 14, 2021
  57. vijaydasmp referenced this in commit c1bb713f6c on Nov 14, 2021
  58. vijaydasmp referenced this in commit 2c7254f133 on Nov 16, 2021
  59. DrahtBot locked this on Dec 16, 2021


NicolasDorier DrahtBot Sjors MarcoFalke harding

Labels
Docs

Milestone
0.19.0

github-metadata-mirror

This is a metadata mirror of the GitHub repository bitcoin/bitcoin. This site is not affiliated with GitHub. Content is generated from a GitHub metadata backup.
generated: 2025-07-13 12:13 UTC
This site is hosted by @0xB10C
More mirrored repositories can be found on mirror.b10c.me