Opened 7 years ago

Closed 7 years ago

#2230 closed task (fixed)

perfdhcp Documentation

Reported by: stephen Owned by: marcin
Priority: medium Milestone: Sprint-DHCP-20121004
Component: documentation Version:
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: 0
Total Hours: 0 Internal?: no

Description

Write perfdhcp documentation:

  • Usage documentation (man page, entry into the BIND 10 manual)
  • Programmer overview (object breakdown, possibly in the form of a Doxygen page)

Subtickets

Change History (9)

comment:1 Changed 7 years ago by stephen

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

comment:2 Changed 7 years ago by marcin

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

I filled in section titled "perfdhcp" in DHCP Performance Guide (tests/tools/dhcp-perf-guide.xml). I created another document (in docbook again) in tests/tools/perfdhcp/perfdhcp-classes.xml where I gave a brief overview of major perfdhcp classes with simple use examples.

I postponed any updates to wiki (http://bind10.isc.org/wiki/DhcpBenchmarking) until we actually close #1959, #1960 (and maybe release new perfdhcp?).

Please review trac2230.

comment:3 Changed 7 years ago by stephen

  • Owner changed from UnAssigned to stephen

comment:4 follow-up: Changed 7 years ago by stephen

  • Owner changed from stephen to marcin

Reviewed commit 8f915dfd4719f03ba41c58b0524ab05054e0628c

dhcp-perf-guide.xml
Good introduction. We will need to extend it with more examples, but not just yet - that can wait until we get experience of using perfdhcp ourself.

I've made a number of editorial changes - English, phrasing etc. - and pushed the result.

I've also altered the text of the introduction - this is being pushed as a test tool, and so the text does not need anything about elimintaing bugs or trying out new DHCP designs.

I've also moved the description of perfdhcp as a relay before the example that talks about setting port numbers (and which also refers to relays).

The only thing I found lacking was in the description of template files. What is missing is:

  • Indication that the -T option can be specified multiple times, for (in order) outgoing DISCOVER/REQUEST or SOLICIT/REQUEST packets.
  • Format of the file. In some cases the text says that the file contains binary and in other cases it contains hexadecimal digits.
  • Use of -O: the help text describes it as "Offset of last octet to randomise in the template". Does this mean that everying in the packet up to that octet is randomised? How is a specified byte randomised (as opposed to a two- or four- byte integer)? If I randomise client ID, is the number of random values controlled by -R?
  • Does the template file contain just one template? If multiple templates are specified in the file, are they used in order?

perfdhcp-classes.xml
The text is OK, but I envisaged it as being in Doxygen format and forming part of the BIND 10 Developers' guide.

I've created branch trac2230-doxygen that contains the text formatted in Doxygen format: check out this branch and after configuring the system, "cd" to the "doc" directory and issue the command "make devel" to run Doxygen. The Doxygen document can be seen by opening "html/index.html" in any browser: the perfdhcp entry will be found in the "BIND 10 Developer's Guide" section.

If you're happy with this change, merge trac2230-doxygen into trac2230.

comment:5 in reply to: ↑ 4 Changed 7 years ago by marcin

  • Owner changed from marcin to stephen

Replying to stephen:

Reviewed commit 8f915dfd4719f03ba41c58b0524ab05054e0628c

dhcp-perf-guide.xml
Good introduction. We will need to extend it with more examples, but not just yet - that can wait until we get experience of using perfdhcp ourself.

I've made a number of editorial changes - English, phrasing etc. - and pushed the result.

I've also altered the text of the introduction - this is being pushed as a test tool, and so the text does not need anything about elimintaing bugs or trying out new DHCP designs.

I am not convinced. The purpose of the test tool is to find bugs and correct them. It is useless to find the bug/performance bottle neck if you're not planning to fix it. Also I claim that it may be useful to try different designs based on results we get from perfdhcp.

I've also moved the description of perfdhcp as a relay before the example that talks about setting port numbers (and which also refers to relays).

The only thing I found lacking was in the description of template files. What is missing is:

  • Indication that the -T option can be specified multiple times, for (in order) outgoing DISCOVER/REQUEST or SOLICIT/REQUEST packets.

I added some extra description.

  • Format of the file. In some cases the text says that the file contains binary and in other cases it contains hexadecimal digits.

I replaced word "binary" with something more appropriate.

  • Use of -O: the help text describes it as "Offset of last octet to randomise in the template". Does this mean that everying in the packet up to that octet is randomised? How is a specified byte randomised (as opposed to a two- or four- byte integer)? If I randomise client ID, is the number of random values controlled by -R?

I agree this is confusing. I added paragraph to explain that more throughly.

  • Does the template file contain just one template? If multiple templates are specified in the file, are they used in order?

One template-file specifies exactly one packet template. I added some note regarding it.

perfdhcp-classes.xml
The text is OK, but I envisaged it as being in Doxygen format and forming part of the BIND 10 Developers' guide.

Thanks. Nice work. I think it looks better now.

I've created branch trac2230-doxygen that contains the text formatted in Doxygen format: check out this branch and after configuring the system, "cd" to the "doc" directory and issue the command "make devel" to run Doxygen. The Doxygen document can be seen by opening "html/index.html" in any browser: the perfdhcp entry will be found in the "BIND 10 Developer's Guide" section.

If you're happy with this change, merge trac2230-doxygen into trac2230.

Instead of merging I cherry-picked this commit. The commits history will look cleaner if we have one branch instead of two.

comment:6 Changed 7 years ago by stephen

  • Owner changed from stephen to marcin

I am not convinced. The purpose of the test tool is to find bugs and correct them. It is useless to find the bug/performance bottle neck if you're not planning to fix it. Also I claim that it may be useful to try different designs based on results we get from perfdhcp.

Possibly, but the main aim of the tool was as a performance checker. Let's leave it unchanged for now, we can always alter it later.

For the rest, I think it is OK with the exception of:

The content in template files is encoded in hexadecimal format.

It's still not clear whether this means the file is binary, or ASCII with data encoded as a series of hexadecimal digits.(And if binary format, is the information encoded in host-byte order or network-byte order? Is it possible to use a template file created on one machine on another machine with a different "endianess"?)

comment:7 Changed 7 years ago by marcin

  • Owner changed from marcin to stephen

Comment added.

comment:8 Changed 7 years ago by stephen

  • Owner changed from stephen to marcin

Review commit 750f6fecbe3e5e8b74a309679b129e35895fc841

That clears it up - please merge.

(BTW. I assume that embedded spaces are allowed, e.g. "12 5f 7e" is permissible.)

comment:9 Changed 7 years ago by marcin

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

Thanks. I merged the documentation to master.

The embedded spaces are not allowed but it can be added with #1960.

Note: See TracTickets for help on using tickets.