Commit cf68d084 authored by Stephen Morris's avatar Stephen Morris
Browse files

[4299] Minor edits during review

parent 9558de51
...@@ -10,32 +10,35 @@ ...@@ -10,32 +10,35 @@
@section configBackendIntro Introduction @section configBackendIntro Introduction
Kea started as a sub-project in BIND10 that used bindctl to deliver Kea started as a sub-project in BIND10 that used a program (called
configuration to its modules. After BIND10 was cancelled, Kea project bindctl) to deliver configuration information to its modules. This
briefly tried to maintain backward compatibility with the BIND10 framework, potentially allowed for modules to get their configuration information
but the idea has been promptly dropped due to lack interest. in a variaty of ways using what were known as configuration backends.
After BIND10 was cancelled, the Kea project briefly tried to maintain
backward compatibility with the BIND10 framework, but the effort
was discontinued due to lack of interest.
Currently Kea team does not foresee any additional configuration Currently the Kea team does not plan to develop any additional
backends to be developed. Instead, an effort is being made to enhance configuration backends. Instead, effort is being focused on enhancing
current control channel (see @ref ctrlSocket) to be as flexible as the current control channel (see @ref ctrlSocket) to be as flexible
possible. If you are thinking about developing new ways to configure as possible. If you are thinking about developing new ways to
Kea, the recommendation is to write an external piece of software that configure Kea, the recommendation is to write an external piece of
will communicate with Kea using control channel. software that will communicate with Kea using this channel.
@section configBackendHistoric Historic Notes @section configBackendHistoric Historic Notes
While this section currently has not practical value, it may become useful While this section currently has no practical value, it may become useful
one day to develop a minimalistic, stripped down Kea version that does one day to develop a minimalistic, stripped down Kea version that does
not have any command interface at all. This could prove useful for running not have any command interface at all. This could prove useful for running
Kea in embedded regime. Kea in embedded regime.
The following steps are needed were conducted for the DHCPv4 server to The following steps are needed for the DHCPv4 server to be able to
be able to process configuration. (It is assumed that the modified process a new method of configuration. (It is assumed that the
component is DHCPv4. Similar approach applies to the other components: modified component is DHCPv4. Similar approach applies to the other
DHCPv6 or DHCP-DDNS): components: DHCPv6 or DHCP-DDNS):
-# Write your own implementation of isc::dhcp::ControlledDhcpv4Srv::init(), -# Write your own implementation of isc::dhcp::ControlledDhcpv4Srv::init(),
isc::dhcp::ControlledDhcpv4Srv::init() and isc::dhcp::ControlledDhcpv4Srv::cleanup() isc::dhcp::ControlledDhcpv4Srv::init() and isc::dhcp::ControlledDhcpv4Srv::cleanup(),
and put it in the src/bin/dhcp4 directory (e.g. as foo_controller.cc). and put it in the src/bin/dhcp4 directory (e.g. as foo_controller.cc).
-# Modify src/bin/dhcp4/Makefile.am to include your file (e.g. foo_controller.cc) in -# Modify src/bin/dhcp4/Makefile.am to include your file (e.g. foo_controller.cc) in
the build. the build.
......
...@@ -94,10 +94,10 @@ on the multitude of systems we run Kea on. It is short-sighted, because ...@@ -94,10 +94,10 @@ on the multitude of systems we run Kea on. It is short-sighted, because
even with your best intentions you will not be able to dedicate even with your best intentions you will not be able to dedicate
any significant amount of time for repeated testing of your improved any significant amount of time for repeated testing of your improved
code. The old ISC DHCP has two decades of history behind it and we code. The old ISC DHCP has two decades of history behind it and we
hope to make Kea last similar time span. Over such large periods of hope to make Kea last similar time span. Over such long periods,
time, code tends to be refactored several times. The change you code tends to be refactored several times. The change you
made may be affected by some other change or by the code that made may be affected by some other change or by the code that
does not even exist yet. hasn't been written yet.
See @ref unitTests for instructions on how to run unit-tests. If you See @ref unitTests for instructions on how to run unit-tests. If you
happen to touch any database related code, make sure you compile happen to touch any database related code, make sure you compile
...@@ -135,56 +135,56 @@ There are several ways how you can send your changes. They are listed ...@@ -135,56 +135,56 @@ There are several ways how you can send your changes. They are listed
here from most to least preferred. here from most to least preferred.
- Send pull request (PR) on github. This is by far the most convenient way for - Send pull request (PR) on github. This is by far the most convenient way for
everyone. See excellent documentation on github: everyone. See the excellent documentation on github:
https://help.github.com/articles/creating-a-pull-request/ for details. In https://help.github.com/articles/creating-a-pull-request/ for details. In
essence, you need github account (spam/hassle free, takes 1 minute to set essence, you need github account (spam/hassle free, takes one minute to set
up). Then you can fork Kea repo, commit changes to your repo and ask us to pull up). Then you can fork the Kea repository, commit changes to your repo and ask us to pull
your changes into official Kea repo. It has a number of advantages. First, it is your changes into official Kea repository. This has a number of advantages. First, it is
made against specific code version, which can be easily checked with git log made against a specific code version, which can be easily checked with git log
command. Second, this request pops up instantly on our list of open pull command. Second, this request pops up instantly on our list of open pull
requests and will stay there. Third benefit is that pull request mechanism is requests and will stay there. The third benefit is that the pull request mechanism is
very flexible. Kea engineers (and other users, too) can comment on it, attach very flexible. Kea engineers (and other users, too) can comment on it, attach
links, mention other users etc. You as a submitter can augment the patch by links, mention other users etc. You as a submitter can augment the patch by
commiting extra changes to your repo. Those extra commits will appear instantly commiting extra changes to your repository. Those extra commits will appear instantly
in the PR. This is super useful during the review. Finally, ISC engineers can in the pull request. This is really useful during the review. Finally, ISC engineers can
better assess all open PRs and add labels to them, like enhancement, bug, or better assess all open pull requests and add labels to them, such as "enhancement", "bug", or
unit-tests missing. This makes our life easier. Oh, and your commits will later "unit-tests missing". This makes our life easier. Oh, and your commits will later
be shown as yours in github history. If you care for that kind of things, once the be shown as yours in github history. If you care for that kind of things, once the
patch is merged, you'll be automatically listed as contributor and Kea will be patch is merged, you'll be automatically listed as contributor and Kea will be
listed as project you contributed to. listed as project you have contributed to.
- Create a ticket in Kea trac and attach your patch to it. Sending a patch has a - Create a ticket in the Kea trac and attach your patch to it. Sending a patch has a
number of disadvantages. First, if you don't specify the base version against number of disadvantages. First, if you don't specify the base version against
which it was created, one of ISC engineers will have to guess that or go through which it was created, one of ISC engineers will have to guess that or go through
a series of trials and errors to find that out. If the code doesn't compile, the a series of trials and errors to find that out. If the code doesn't compile, the
reviewer will not know if the patch is broken or maybe it was applied to reviewer will not know if the patch is broken or maybe it was applied to
incorrect base code. Another frequent problem is that it may be possible that incorrect base code. Another frequent problem is that it may be possible that
the patch didn't include any new files you have added. If we happen to have any the patch didn't include any new files you have added. If we happen to have any
comments that you as submitter is expected to address (in overwhelming majority comments that you as submitter are expected to address (and in the overwhelming majority
of cases we have), you will be asked to send an updated patch. It is not of cases, we have), you will be asked to send an updated patch. It is not
uncommon to see several rounds of such reviews, so this can get very complicated uncommon to see several rounds of such reviews, so this can get very complicated
very quickly. Please make sure your ticket is created in the default milestone very quickly. Please make sure your ticket is created in the default milestone
kea-proposed. ISC engineers review new tickets once a week and assign them to "kea-proposed". ISC engineers review new tickets once a week and assign them to
specific milestones. Please do not add tickets to working milestones directly. specific milestones. Please do not add tickets to working milestones directly.
Having a ticket in trac ensures that the patch will never be forgotten and it Having a ticket in trac ensures that the patch will never be forgotten and it
will show up on our trac reports. It's not required, but much appreciated if will show up on our trac reports. It's not required, but much appreciated if
you send a short note to the kea-dev explaining what you did with the code you send a short note to the kea-dev mailing list explaining what you did with the code
and announce the ticket number. and announce the ticket number.
- Send a patch to the kea-dev list. This is the third preferred method, if you - Send a patch to the kea-dev list. This is the third preferred method, if you
can't or don't want to use github and trac for whatever reason. Finally, if you can't or don't want to use github and trac for whatever reason. If you
send a patch to a mailing list in a wrong time, e.g. shortly before a release, send a patch to a mailing list in a wrong time, e.g. shortly before a release,
ISC engineers may miss it or perhaps they will see it and then forget about ISC engineers may miss it or perhaps they will see it and then forget about
it. Nevertheless, it is still doable and we successfully accepted patches that it. Nevertheless, it is still doable and we successfully accepted patches that
way. It just takes more time from everyone involved, so it's a slower process in way. It just takes more time from everyone involved, so it's a slower process in
general. general.
- Send the tarball with your modified code. This is really the worst way one - Send a tarball with your modified code. This is really the worst way one
can contribute a patch. It has a number of disadvantages. In particular, someone can contribute a patch. It has a number of disadvantages. In particular, someone
will need to find out which version the code was based on and generate the will need to find out which version the code was based on and generate the
patch. It's not a rocket science, but it may be a very mundane thing to do patch. It's not a rocket science, but it may be a very mundane thing to do
if the ISC engineer does not know the version in advance. The mailing list if the ISC engineer does not know the version in advance. The mailing list
has a limit of message size (for good reasons), so you'll likely need to has a limit on the message size (for good reasons), so you'll likely need to
upload it somewhere first. ISC engineers often don't pick up new tickets upload it somewhere first. ISC engineers often don't pick up new tickets
instantly, so it may have to wait weeks before the tarball is looked at. instantly, so it may have to wait weeks before the tarball is looked at.
The tarball does not benefit from most of the advantages mentioned for github, The tarball does not benefit from most of the advantages mentioned for github,
...@@ -231,11 +231,11 @@ notes. ...@@ -231,11 +231,11 @@ notes.
Sadly, we sometimes see patches that are submitted and then the submitter never Sadly, we sometimes see patches that are submitted and then the submitter never
responds to our comments or requests for an updated patch. Depending on the responds to our comments or requests for an updated patch. Depending on the
nature of the patch, we may either fix the outstanding issues on our own and get nature of the patch, we may either fix the outstanding issues on our own and get
another ISC engineer to review them or the ticket may end up in Outstanding another ISC engineer to review them or the ticket may end up in our "Outstanding
tasks milestone. When a new release is started, we go through the tickets in Tasks" milestone. When a new release is started, we go through the tickets in
Outstanding tasks and pick a small number of them and move them to whatever the Outstanding Tasks, select a small number of them and move them to whatever the
current milestone is. Keep that in mind if you plan to submit a patch and forget current milestone is. Keep that in mind if you plan to submit a patch and forget
about it. We may accept it eventually, but it's much, much after process if you about it. We may accept it eventually, but it's much, much faster process if you
participate in it. participate in it.
@section contributorGuideExtra Extra steps @section contributorGuideExtra Extra steps
......
...@@ -12,7 +12,7 @@ ...@@ -12,7 +12,7 @@
* provides information needed to extend and maintain Kea source code. * provides information needed to extend and maintain Kea source code.
* If you wish to write hook code - the code that is loaded by Kea at * If you wish to write hook code - the code that is loaded by Kea at
* the run-time and modifies its behavior, you should read the section * run-time and modifies its behavior, you should read the section
* @ref hooksdgDevelopersGuide. * @ref hooksdgDevelopersGuide.
* *
* Kea maintenance information is divided into a number of sections. * Kea maintenance information is divided into a number of sections.
......
...@@ -301,6 +301,6 @@ specified at server startup. The location of this file is held in the ...@@ -301,6 +301,6 @@ specified at server startup. The location of this file is held in the
For hooks API support in DHCPv4, see @ref dhcpv4Hooks. For hooks API support in DHCPv4, see @ref dhcpv4Hooks.
For description of how DHCPv4-over-DHCPv6 is implemented, see @subpage dhcpv4o6Dhcp4. For a description of how DHCPv4-over-DHCPv6 is implemented, see @subpage dhcpv4o6Dhcp4.
*/ */
...@@ -93,12 +93,12 @@ ...@@ -93,12 +93,12 @@
@subsection dhcpdb-keywords-cql Cassandra (CQL) connection string keywords @subsection dhcpdb-keywords-cql Cassandra (CQL) connection string keywords
- <b>contact_points</b> - a list of coma separate IP addresses of the - <b>contact_points</b> - a list of comma separate IP addresses of the
cluster contaict points> cluster contact points>
- <b>port</b> - an integer specifying connection port. If not specified, the - <b>port</b> - an integer specifying a connection port. If not specified, the
default port will be used. default port will be used.
- <b>user</b> - a database user name under which the database is accessed. If - <b>user</b> - a database user name under which the database is accessed. If
not specifed, no user name is used - the database is assumed to be open. not specified, no user name is used - the database is assumed to be open.
- <b>password</b> - an optional password if required for connection - <b>password</b> - an optional password if required for connection
- <b>keyspace</b> - an optional keyspace. If not specified, the default value - <b>keyspace</b> - an optional keyspace. If not specified, the default value
of 'keatest' will be used. of 'keatest' will be used.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment