Opened 5 years ago

Closed 3 years ago

#3684 closed enhancement (complete)

Host storage in MySQL must be documented

Reported by: tomek Owned by: marcin
Priority: medium Milestone: Kea1.1-final
Component: documentation Version: git
Keywords: Cc:
CVSS Scoring: Parent Tickets:
Sensitive: no Defect Severity: N/A
Sub-Project: DHCP Feature Depending on Ticket:
Estimated Difficulty: 0 Add Hours to Ticket: 2
Total Hours: 6 Internal?: no

Description (last modified by tomek)

Once tickets #3681, #3567, #3682, #3569 and #3683 are done, the
solution should be documented in Kea User's Guide.

Subtickets

Change History (16)

comment:1 Changed 5 years ago by tomek

  • Milestone changed from Kea-proposed to Kea1.0

comment:2 Changed 5 years ago by tomek

  • Milestone changed from Kea1.0 to Kea0.9.1

comment:3 Changed 5 years ago by marcin

  • Milestone changed from Kea0.9.1 to Kea1.1

comment:4 Changed 3 years ago by tomek

  • Description modified (diff)

There's a boilerplate text added in #4518 (now on master) that references Marcin's wiki page:
http://kea.isc.org/wiki/HostReservationsHowTo

Also, once this is done please handle PR#20: https://github.com/isc-projects/kea/pull/20

It's very short and we want to encourage people to share small improvements like this, so we should acknowledge the submitter.

comment:5 Changed 3 years ago by tomek

During #4277 review it was discovered that while the schema allows storing options of arbitrary length, the code uses 4K buffers. Therefore this doc change should do as follows.

Sections 7.3.5, 7.3.6, 8.3.5 and 8.3.6 should be updated. Adding a sentence like this would address this issue:

"Currently maximum length of options specified per host is arbitrarily set to 4096 bytes."

comment:6 Changed 3 years ago by tomek

  • Milestone changed from Kea1.1 to Kea1.1-final

comment:7 Changed 3 years ago by marcin

  • Owner set to marcin
  • Status changed from new to accepted

I assign this ticket to myself but I am going to wait for #4279 merge to make sure that whatever we apply for MySQL documentation is also consistent with PostgreSQL documentation.

comment:8 Changed 3 years ago by marcin

  • Owner changed from marcin to UnAssigned
  • Status changed from accepted to reviewing

I have added ChangeLog:

11XX.	[doc]		marcin
	Updated Kea Administrator's Reference Manual sections
	regarding host reservations. Added configuration examples
	for using host reservations with MySQL and PostgreSQL
	databases.
	(Trac #3684, git abcd)

comment:9 Changed 3 years ago by marcin

  • Add Hours to Ticket changed from 0 to 4
  • Total Hours changed from 0 to 4

comment:10 Changed 3 years ago by stephen

  • Owner changed from UnAssigned to stephen

comment:11 follow-up: Changed 3 years ago by stephen

  • Owner changed from stephen to marcin

Reviewed commits 8cd0316dda05707e9d233bc98adcf65c39ea0417 through 0aeb76d82fc9ecee82c8ac8699b2d33517602f5e

doc/examples/kea{4,6}/{my,pg}sql-reservations.json
Line 13: Suggest modifying to:

We need to specify the the database used to store leases. As of September 2016, four database backends are supported: MySQL, PostgreSQL, Cassandra, and the in-memory database, Memfile. We'll use memfile...

Logging clause: Suggest that wording is rephrased to:

The following configures logging. It specifies that all messages with a severity of information or higher (warning and error) will be logged to stdout.

("information" should be "debug" in the V6 examples.) Note that the wording in the V6 examples seem to suggest that only debug messages will be logged to the log file when in fact all messages will be copied there.

(DHCPv4 examples only)
Line 20:
This is confusing. The comment says

# Addresses will be assigned with valid lifetimes being 4000. Client
# is told to start renewing after 1000 seconds. If the server does not respond
# after 2000 seconds since the lease was granted, client is supposed...

However, the renew-timer and rebind-timer parameters are commented out a couple of lines further on, so are these default values? If so, the comment should say this.

doc/guide/dhcp6-srv.xml
Section "Host Reservation in DHCPv6": In...

IAs and dynamically allocate addresses or prefixes to remaining IAs. If the server cannot assign any of the reserved addresses or prefixes because of the conflict,

... what conflict? Does the text mean "because of a conflict" or "because it is in use"?

Other
The table in section 4.3 of the Admin Guide "Supported Databases" needs to be changed to indicate that Host Reservation is supported in PostgreSQL.

There are a number of grammatical errors in the host reservation documentation (not in the bits you've changed). An editing pass is needed, which is another task (#4484).

ChangeLog looks OK.

comment:12 in reply to: ↑ 11 Changed 3 years ago by marcin

  • Add Hours to Ticket changed from 4 to 2
  • Owner changed from marcin to stephen
  • Total Hours changed from 4 to 6

Replying to stephen:

Reviewed commits 8cd0316dda05707e9d233bc98adcf65c39ea0417 through 0aeb76d82fc9ecee82c8ac8699b2d33517602f5e

doc/examples/kea{4,6}/{my,pg}sql-reservations.json
Line 13: Suggest modifying to:

We need to specify the the database used to store leases. As of September 2016, four database backends are supported: MySQL, PostgreSQL, Cassandra, and the in-memory database, Memfile. We'll use memfile...

I applied this change to several example files.

Logging clause: Suggest that wording is rephrased to:

The following configures logging. It specifies that all messages with a severity of information or higher (warning and error) will be logged to stdout.

("information" should be "debug" in the V6 examples.) Note that the wording in the V6 examples seem to suggest that only debug messages will be logged to the log file when in fact all messages will be copied there.

I updated comment above logging configuration in many example files.

(DHCPv4 examples only)
Line 20:
This is confusing. The comment says

# Addresses will be assigned with valid lifetimes being 4000. Client
# is told to start renewing after 1000 seconds. If the server does not respond
# after 2000 seconds since the lease was granted, client is supposed...

However, the renew-timer and rebind-timer parameters are commented out a couple of lines further on, so are these default values? If so, the comment should say this.

True. So, I removed the confusing commentary from several files.

doc/guide/dhcp6-srv.xml
Section "Host Reservation in DHCPv6": In...

IAs and dynamically allocate addresses or prefixes to remaining IAs. If the server cannot assign any of the reserved addresses or prefixes because of the conflict,

... what conflict? Does the text mean "because of a conflict" or "because it is in use"?

The word "conflict" we use in host reservations to describe the fact that the address can't be assigned because it is used. But, I made suggested change to make it clearer.

Other
The table in section 4.3 of the Admin Guide "Supported Databases" needs to be changed to indicate that Host Reservation is supported in PostgreSQL.

Updated.

There are a number of grammatical errors in the host reservation documentation (not in the bits you've changed). An editing pass is needed, which is another task (#4484).

Yes. I prefer that to be corrected as part of the #4484.

ChangeLog looks OK.

Thanks.

comment:13 follow-up: Changed 3 years ago by stephen

  • Owner changed from stephen to marcin

Reviewed commits 05072326f3f8756e20641a3c12fa378d967fcc2f through 0a7591f0c9b5afe7fdc5a481f931a5db0ebce5e6.

doc/examples/kea4/backends.json
doc/examples/kea4/leases-expiration.json
doc/examples/kea4/multiple-options.json
doc/examples/kea4/mysql-reservations.json
doc/examples/kea4/mysql-reservations.json
doc/examples/kea4/pgsql-reservations.json
doc/examples/kea4/reservations.json
doc/examples/kea4/several-subnets.json
doc/examples/kea4/single-subnet.json
doc/examples/kea6/advanced.json
doc/examples/kea6/backends.json
doc/examples/kea6/classify.json
doc/examples/kea6/duid.json
doc/examples/kea6/leases-expiration.json
doc/examples/kea6/multiple-options.json
doc/examples/kea6/mysql-reservations.json
doc/examples/kea6/pgsql-reservations.json
doc/examples/kea6/reservations.json

Where relevant (numerous files):

Suggest changing

Addresses will be assigned with valid lifetimes being 4000.

to

Addresses will be assigned with a lifetime of 4000 seconds.

Also, in:

# The following configures logging. It assumes that messages with at least
# informational level (info, warn, error) will will be logged to stdout.

s/will will be logged/should be logged/
s/info, warn, error/info, warn, error and fatal/

In addition to the above comments:

doc/examples/kea4/several-subnets.json
# Client is told to start renewing after 1000 seconds. If the server
# does not respond after 2000 seconds since the lease was granted, client
# is supposed to start REBIND procedure (emergency renewal that allows
# switching to a different server).

"valid-lifetime": 4000,
"renew-timer": 1000,
"rebind-timer": 2000,

s/Client/The client/
s/does not respond after 2000 seconds since the lease was granted/does not respond within 2000 seconds of the lease being granted/

Question about that last change: the text implies that both the renew timer and the rebind timer are started when the lease is granted. What happens if the renew timer is greater than the rebind timer? Will the client not attempt to renew but immediately start the rebind procedure? Should Kea guard against such a configuration?

comment:14 in reply to: ↑ 13 Changed 3 years ago by marcin

  • Owner changed from marcin to stephen

Replying to stephen:

Reviewed commits 05072326f3f8756e20641a3c12fa378d967fcc2f through 0a7591f0c9b5afe7fdc5a481f931a5db0ebce5e6.

doc/examples/kea4/backends.json
doc/examples/kea4/leases-expiration.json
doc/examples/kea4/multiple-options.json
doc/examples/kea4/mysql-reservations.json
doc/examples/kea4/mysql-reservations.json
doc/examples/kea4/pgsql-reservations.json
doc/examples/kea4/reservations.json
doc/examples/kea4/several-subnets.json
doc/examples/kea4/single-subnet.json
doc/examples/kea6/advanced.json
doc/examples/kea6/backends.json
doc/examples/kea6/classify.json
doc/examples/kea6/duid.json
doc/examples/kea6/leases-expiration.json
doc/examples/kea6/multiple-options.json
doc/examples/kea6/mysql-reservations.json
doc/examples/kea6/pgsql-reservations.json
doc/examples/kea6/reservations.json

Where relevant (numerous files):

Suggest changing

Addresses will be assigned with valid lifetimes being 4000.

to

Addresses will be assigned with a lifetime of 4000 seconds.

I made these changes.

Also, in:

# The following configures logging. It assumes that messages with at least
# informational level (info, warn, error) will will be logged to stdout.

s/will will be logged/should be logged/
s/info, warn, error/info, warn, error and fatal/

I also made these changes.

In addition to the above comments:

doc/examples/kea4/several-subnets.json
# Client is told to start renewing after 1000 seconds. If the server
# does not respond after 2000 seconds since the lease was granted, client
# is supposed to start REBIND procedure (emergency renewal that allows
# switching to a different server).

"valid-lifetime": 4000,
"renew-timer": 1000,
"rebind-timer": 2000,

s/Client/The client/
s/does not respond after 2000 seconds since the lease was granted/does not respond within 2000 seconds of the lease being granted/

Updated.

Question about that last change: the text implies that both the renew timer and the rebind timer are started when the lease is granted. What happens if the renew timer is greater than the rebind timer? Will the client not attempt to renew but immediately start the rebind procedure? Should Kea guard against such a configuration?

The DHCP protocol mandates the renew timer be equal or lower than rebind timer. Configuration where rebind timer is lower than renew timer doesn't really make sense. The server currently doesn't guard (AFAIK) against this misconfiguration but there is a ticket to fix that (#3452).

comment:15 Changed 3 years ago by stephen

  • Owner changed from stephen to marcin

Reviewed commit 1fe02beb422ea60aefe407615fc308b457f21f46

All OK, please merge.

comment:16 Changed 3 years ago by marcin

  • Resolution set to complete
  • Status changed from reviewing to closed

Merged with commit 71d21eac51d20ff5d368b17c437abc45c955a04c

Note: See TracTickets for help on using tickets.