docs: update documentation of config data types by pstorz · Pull Request #962 · bareos/bareos

pstorz · 2021-10-21T12:51:31Z

Thank you for contributing to the Bareos Project!

The documentation of the bareos configuration types was not complete and also the types were not linked in the documentation.
This PR adds automatic links beween the directive description and the directive types.
For types that were not described before, documentationt stubs were added.

Also added a more practical example to the ADDRESSES type description.

Please check

Short description and the purpose of this PR is present above this paragraph
Your name is present in the AUTHORS file (optional)

If you have any questions or problems, please give a comment in the PR.

Helpful documentation and best practices

Checklist for the reviewer of the PR (will be processed by the Bareos team)

General

PR name is meaningful
Purpose of the PR is understood
Separate commit for this PR in the CHANGELOG.md, PR number referenced is same
Commit descriptions are understandable and well formatted

bruno-at-bareos

There's some improvement and changes needed (like netport -> port) to be done.

docs/manuals/source/Configuration/CustomizingTheConfiguration.rst

bruno-at-bareos

Please review and comment changes requested.

bruno-at-bareos

There's minors changes requested.

bruno-at-bareos · 2021-10-25T11:57:25Z

I've made some more researches and tests against Bareos > and < 21.
Here's what I believe we should push to documentation.

Bareos Addresses*

For clarity, in the following configuration samples, only FDAddresses is used.
You can of course extend it to DIRAddresses for director and SDAddresses for storage respective daemons.

Before Bareos 21

Without any specific configuration, Bareos daemons will listen on ipv4 protocol all addresseses.

 ss -tanp | grep ":910"
 LISTEN 0      50            0.0.0.0:9102      0.0.0.0:*     users:(("bareos-fd",pid=2234,fd=7))

a) To have listening on ipv6 all addresses (ipv4 all addresses will be still listening)

You need this configuration

  FDAddresses  = {
    ipv6 = { addr = ::; port = 9102 }
  }

  ss -tanp | grep ":910"
  LISTEN 0      50                  *:9102            *:*     users:(("bareos-fd",pid=2286,fd=7))

telnet 127.0.0.1 9102 => connect
telnet ::1 9102 => connect

Never try to have this kind of configuration, even if it seems correct the daemon will start
try to bind to all addresses in ipv4, then ipv6, and then will make again a try for ipv4
and finally will vanish after few seconds with error message "socket already in use."

DONT

  FDAddresses  = {
    ipv6 = { addr = ::; port = 9102 }
    ipv4 = { addr = 0.0.0.0; port = 9102 }
  }

b) To restrict listening on specific ipv4 addresses, keeping ipv6 desactivated you need
this kind of configuration

  FDAddresses  = {
    ipv4 = { addr = 127.0.0.1; port = 9101 }
    ipv4 = { addr = 192.168.0.1; port = 9101 }
  }

  ss -tanp | grep ":910"
  LISTEN 0      50        192.168.0.1:9102      0.0.0.0:*     users:(("bareos-fd",pid=2459,fd=8))
  LISTEN 0      50          127.0.0.1:9102      0.0.0.0:*     users:(("bareos-fd",pid=2459,fd=7))

telnet 127.0.0.1 9102 => connected
telnet ::1 9102 => refused

c) To restrict listening only on ipv6 protocol and specific addresses, disabling
completely ipv4 protocol, you need to add one or more ipv6 addresses.

  FDAddresses  = {
    ipv6 = { addr = ::1; port = 9102 }
    ipv6 = { addr = 2001:0db8:0000:0000:ba4e:0s00:0000:9102; port = 9102 }
  }

  ss -tanp | grep ":910"
  LISTEN 0      50     [2001:0db8:0000:0000:ba4e:0s00:0000:9102]:9102         [::]:*     users:(("bareos-fd",pid=25295,fd=4))
  LISTEN 0      50                                         [::1]:9102         [::]:*     users:(("bareos-fd",pid=2423,fd=7))

telnet 127.0.0.1 9102 => refused
telnet ::1 9102 => connected

Bareos 21 and above

Since version 21, Bareos now use two distinct socket, the behavior is more clear, and easy to configure.

Without specific configuration, Bareos daemons will listen on ipv4 and ipv6 protocol, binding all
addresses.

  ss -tanp | grep ":9102"
  LISTEN    0         50                 0.0.0.0:9102            0.0.0.0:*         users:(("bareos-fd",pid=25075,fd=3))
  LISTEN    0         50                    [::]:9102               [::]:*         users:(("bareos-fd",pid=25075,fd=4))

Using the following configuration will give the same result.

 FDAddresses  = {
   ipv6 = { addr = :: ; port = 9102 }
   ipv4 = { addr = 0.0.0.0; port = 9102 }
 }

a) Listen on all ipv6 addresses, and only localhost for ipv4

 FDAddresses  = {
   ipv6 = { addr = :: ; port = 9102 }
   ipv4 = { addr = 127.0.0.1; port = 9102 }
 }

  ss -tanp | grep ":9102"
  LISTEN    0         50               127.0.0.1:9102            0.0.0.0:*         users:(("bareos-fd",pid=25276,fd=4))
  LISTEN    0         50                    [::]:9102               [::]:*         users:(("bareos-fd",pid=25276,fd=3))

b) Listen on all ipv4 addresses, and none ipv6

 FDAddresses  = {
   ipv4 = { addr = 0.0.0.0; port = 9102 }
 }

  ss -tanp | grep ":9102"
  LISTEN    0         50                 0.0.0.0:9102            0.0.0.0:*         users:(("bareos-fd",pid=22852,fd=3))

c) Listen on specific ipv6 addresses, and none ipv4

 FDAddresses  = {
   ipv6 = { addr = ::1 ; port = 9102 }
   ipv6 = { addr = 2001:0db8:0000:0000:ba4e:0s00:0000:9102; port = 9102 }
 }

 ss -tanp | grep ":9102"
LISTEN 0      50     [2001:0db8:0000:0000:ba4e:0s00:0000:9102]:9102         [::]:*     users:(("bareos-fd",pid=25295,fd=4))
LISTEN 0      50                                         [::1]:9102         [::]:*     users:(("bareos-fd",pid=25295,fd=3))

Co-authored-by: Bruno Friedmann @bareos <89836284+bruno-at-bareos@users.noreply.github.com>

docs/manuals/source/Configuration/CustomizingTheConfiguration.rst

tigerfoot

Review ok

joergsteffens

I just saw, that the Data types chapter and references got updated. Excellent. On a first glance, I saw small formatting issues.

docs/manuals/source/Configuration/CustomizingTheConfiguration.rst

Co-authored-by: Jörg Steffens <joergsteffens@users.noreply.github.com>

Formatting improvements Co-authored-by: Jörg Steffens <joergsteffens@users.noreply.github.com>

bruno-at-bareos

With last formatting improvements

pstorz added 4 commits October 21, 2021 12:29

docs: rename net-addresses to ADDRESSES

bf7835f

docs: link data type to type description

f15127b

docs: add missing type descriptions

25cb3d5

docs: add simple example for ADDRESSES

870b633

pstorz requested a review from bruno-at-bareos October 21, 2021 13:20

bruno-at-bareos approved these changes Oct 21, 2021

View reviewed changes

bruno-at-bareos requested changes Oct 21, 2021

View reviewed changes

bruno-at-bareos reviewed Oct 21, 2021

View reviewed changes