Skip to content

GitLab

Kea
Kea
Source
Select Git revision
...
Target
Select Git revision
 
Commits (2331)
Expand all Show whitespace changes
Inline Side-by-side
Showing with 132381 additions and 59826 deletions

Too many changes to show.

To preserve performance only 1000 of 1000+ files are displayed.
.gitignore
View file @ ac0bbcf6
......@@ -44,4 +44,4 @@ config.h.in~
/local.zone.sqlite3
/logger_lockfile
/report.info
/hammer
.gitlab-ci.yml 0 → 100644
View file @ ac0bbcf6
variables:
# Not normally needed, but may be if some script uses `apt-get install`.
DEBIAN_FRONTEND: noninteractive
# Locale settings do not affect the build, but might affect tests.
LC_ALL: C
CI_REGISTRY_IMAGE: registry.gitlab.isc.org/isc-projects/images/bind9
# Disabled warnings:
# SC2039 - complains about local var: In POSIX sh, 'local' is undefined.
SHELLCHECK_OPTS: "--exclude=SC2039"
stages:
- test
shellcheck:
stage: test
image: "$CI_REGISTRY_IMAGE:debian-stretch-amd64"
before_script:
- sudo apt-get -y install shellcheck
script:
- SCRIPTS="src/bin/keactrl/keactrl.in "
- SCRIPTS+="src/bin/admin/kea-admin.in "
- SCRIPTS+="src/bin/admin/admin-utils.sh "
- SCRIPTS+="tools/cql_config "
- SCRIPTS+="tools/sysrepo_config "
- shellcheck ${SCRIPTS} ${SHELLCHECK_OPTS}
.gitlab/issue_templates/bug_report.md
View file @ ac0bbcf6
......@@ -31,29 +31,5 @@ Add any other context about the problem here. In particular, feel free to share
Make sure you anonymize your config files (at the very lease make sure you obfuscate your database credentials, but you may also replace your actual IP addresses and host names with example.com and 10.0.0.0/8 or 2001:db8::/32).
**Some initial questions**
- Are you sure your feature is not already implemented in the latest Kea version?
- Are you sure what you would like to do is not possible using some other mechanisms?
- Have you discussed your idea on kea-users or kea-dev mailing lists?
**Is your feature request related to a problem? Please describe.**
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
It is very important to describe what you would like to do and why?
**Describe the solution you'd like**
A clear and concise description of what you want to happen.
**Describe alternatives you've considered**
A clear and concise description of any alternative solutions or features you've considered.
**Additional context**
Add any other context about the feature request here.
**Funding its development**
Kea is run by ISC, which is a small non-profit organization without any government funding or any permanent sponsorship organizations. Are you able and willing to participate financially in the development costs?
**Participating in development**
Are you willing to participate in the feature development? ISC team always tries to make a feature as generic as possible, so it can be used in wide variety of situations. That means the proposed solution may be a bit different that you initially thought. Are you willing to take part in the design discussions? Are you willing to test an unreleased engineering code?
**Contacting you**
How can ISC reach you to discuss this matter further? If you do not specify any means such as e-mail, jabber id or a telephone, we may send you a message on github with questions when we have them.
.gitlab/issue_templates/release_checklist.md 0 → 100644
View file @ ac0bbcf6
---
name: Release Checklist
about: Create a new issue using this checklist for each release
---
# Kea Release Process
## Introduction
The Kea release process (for the base version of Kea and the hooks) is different to that of DHCP. At the moment, Kea has only one supported release at a time, so the process tries to ensure that any modifications needed for a release take place on the master branch, rather than on a version-specific one. The basic steps for a release are:
1) Announce a code freeze for the master branch that will last until actual tarball release
2) Do all necessary changes to the master branch for the release
3) Create release tarball from master branch
4) After sanity checks made by the QA and development teams, either we continue or we accept changes on master to fix issues if needed and go back to the previous step.
5) Create a release branch (for beta) or merge master to existing release branch (for final) and tag release on it. (???)
6) Sign and upload tarballs
7) Announce that freeze time on master branch is over.
8) Release tarballs are prepared by Jenkins job: https://jenkins.isc.org/job/kea-master-tarball-internal/. When given tarball is accepted for releasing it is pushed to repo.isc.org using Jenkins job: https://jenkins.isc.org/job/kea-release-upload-internal/
## Pre-Release Preparation
Some of those checks and updates can be made before actual freeze, but it's reasonable to announce freeze now!
- [ ] 1. Check Jenkins results:
* Number of unit tests and system tests failing
* Is there a change in system tests pass rate? *Notify the development team of the overall Jenkins status
* Look into tarball check report " Kea Build Checks" on last tarball build and check if there is nothing suspicious (add/removed files, etc), verify that with developers:
* Compare current release package with code in repository
* Compare current release package with previous release package
- [ ] 2. Is the distcheck passing on kea and kea+premium (https://jenkins.isc.org/job/kea-master-distcheck/)?
* Highlight any issues that require fixing.
- [ ] 3. Check perflab if there is no critical errors there (https://perflab.isc.org/)
- [ ] 4. Make sure that there is no pending ticket to merge! (Use GitLab https://gitlab.isc.org/isc-projects/kea/merge_requests and https://gitlab.isc.org/isc-private/kea-premium/merge_requests or contact the development team).
- [ ] 5. Check the Known Issues list, is there something that suppose to be fixed before release and was omitted?
- [ ] 6. Check versioning:
* Ask the development team if the library versions are being updated (there is a step to check it later).
* Ask the development team if the HOOKS_VERSION is being updated.
- [ ] 7. Create Release Notes on Kea GitLab wiki using standard template, update all dates and versions. This wiki page should created under "release notes" folder, like this one: release-notes-1.5-final
- [ ] 8. Check if there is a Release Checklist ready. If not, create new one using this template (page could have been created, check Releases section at the bottom of this page)
The following steps may involve changing files in the repository. If any files will be updated, create a Kea ticket for them and make the changes on a separate branch.
- [ ] 1. Check User's Guide sections:
* Chapter 1. Introduction
- On what platforms we are running tests using Jenkins? Update Supported Platforms
- Did we add any additional 3rd party software? Update if needed
- Is there a new tool installed in bin or sbin released this time? If yes, is it documented?
* Chapter 2. Quick Start
- Has the default installation process changed (for kea and hooks)? If yes, are those changes documented and highlighted in the release notes?
* Chapter 3. Installation
- Check installation hierarchy
- Check and update Building Requirements
- Check configure options against what ./configure -h says
- [ ] 2. Check !ChangeLog entries in Kea main and premium:
* Spelling, missing numbers, trailing whatspaces? (some of that is checked in every build of tarball-internal Jenkins job)
* Update Release Notes with !ChangeLog entries
- [ ] 3. Check AUTHORS, INSTALL, README files in Kea main and premium.
- [ ] 4. Update information in sources about copyright dates, new version, etc. This is done manually using script https://gitlab.isc.org/isc-private/qa-dhcp/blob/master/kea/build/prepare_kea_release.sh
- [ ] 5. Regenerate parsers using docs.isc.org:
* download kea repo
```
cd kea; autoreconf -fi; ./configure --with-log4cplus=/home/wlodek/log4cplus --enable-generate-parser (log4cplus in /home/wlodek should be available for everyone, if not - download your own)
export PATH=/home/fdupont/bin:$PATH
cd ~/kea/src/bin/dhcp4; touch *.yy; make parser
cd ~/kea/src/bin/dhcp6; touch *.yy; make parser
cd ~/kea/src/bin/d2; touch *.yy; make parser
cd ~/kea/src/bin/agent; touch *.yy; make parser
cd ~/kea/src/bin/netconf/; touch *.yy; make parser
cd ~/kea/src/lib/eval; touch *.yy; make parser
```
TODO: we should regenerate all of them or just the one that been modified?
If changes were made, commit the change, push the branch to the main repository and request a review. Once the changes have been approved, merge the branch to master.
## Build selection and upload package
That is the last moment to freeze code!
- [ ] 1. Update release version in configure.ac and remove -git suffix, and commit the change on master. From that moment all tarball builds can be officially released.
- [ ] 2. Go to tarball-internal Jenkins job and pick last tarball build - it will be a release candidate.
- [ ] 3. Tarball checks before requesting sanity checks from dev team
* Download tarballs from picked jenkins build
Untar packages:
* Check sizes - is new package reasonable?
* Check installation tree, compare it with previous release
* Check installed lib versions
* which were updated? (save results)
* any of the lib from current release has lower number then corresponding lib from previous release? (!)
* Uninstall Kea, check what left (there should be just configuration files)
* Check if all of installed binaries has man page
* if not, is it in the tarball?
* are man page up-to-date?
* Check if documentation is properly formatted, has correct versions and dates.
* it's advised to search for previous version numbers, some of them are statically added in statements that are no longer valid
- [ ] 4. If all seems to be ok then upload tarballs to repo.isc.org
* Go to release-upload Jenkins job
* Click "Build with Parameters"
* In field "Tarball" select picked tarball build
* In field "Release_Candidate" pick:
* rc1 if this is the first selected build for release, it will push selected tarballs to repo.isc.org, to folder suffixed with indicated rc#
* next rc# if this is a respin after some fixes (note: it is not possible to pick previous rc number - it will result in error)
* final if the last rc number was ok, this will push selected tarbal to repo.isc.org, to folder with no suffixes
- [ ] 5. If none of the results force you to fix and rebuild package, send sanity check request by an email to dhcp-team@isc.org and qa@isc.org with indicating paths with tarballs on repo.isc.org asking for sanity checks
## Sanity checks proposals:
- [ ] 1. Check documentation:
* users guide:
- dates, versions, installation instructions both for kea and premium, formatting
- if you have time - read as much as you can.
* man pages:
- dates, versions, is it up-to-date? or usage changed between releases?
- does every binary has it's own .8 page?
- [ ] 2. Check tarball content:
* compare tarball against repo (does some of the not included files should actually be included?)
* does premium tarballs include correct hooks? (any missing files?)
- [ ] 3. compile:
* configure warnings?
* build warnings?
- [ ] 4. run unit tests with various db backends, install (check tree), uninstall (check tree)
- [ ] 5. Check example configurations
- [ ] 6. Check release notes (not included in tarball)
- [ ] 7. Check AUTHORS, INSTALL, COPYING, README files
- [ ] 8. Check db update scripts:
* tarball inlcude the last one? (compare with repo)
## Releasing tarballs:
- [ ] 1. Write an email to signers@isc.org requesting signatures of final tarballs on repo.isc.org indicating release folders. - Attach SHA256 checksums from tarball-internal logs.
- [ ] 2. Make release branch (e.g. v1_5_0 one branch for beta and final, with tags for both releases)
- [ ] 3. Upload Release Notes to repo.isc.org
- [ ] 4. When release packages are signed then upload them from repo.isc.org to ftp:
* make-available --public --symlink=cur /data/shared/sweng/kea/releases/1.4.0-beta
* make-available --private /data/shared/sweng/kea/releases/premium-1.4.0-beta/
* make-available --private /data/shared/sweng/kea/releases/subscription-1.4.0-beta/
- [ ] 5. Contact support or marketing to upload packages to www.isc.org/downloads
- [ ] 6. Contact marketing to upload premium packages to 'products' in web store
- [ ] 7. Contact support to deliver premium and subscriber-only hooks to Kea support subscribers
- [ ] 8. For final release - Release Notes should contain changlogs since previous stable release (beta +final)
- [ ] 9. Modify Release Notes to Announcement
- fold -sw 73 Kea140betaReleaseNotes.txt > Announcement
- change header
- change ftp links to ww.isc.org/downloads
- send it to yourself to check if it's ok
- [ ] 10. Prepare article on kb.isc.org
- change editing mode to HTML, copy release notes between <pre></pre>
- ask support to publish this document
- [ ] 11. Send announcements on:
* kea-users@lists.isc.org
* kea-announce@lists.isc.org
* dhcp-announce@lists.isc.org
- [ ] 12. Notify marketing to announce via social media, publish any blog post that is planned
* publish any blog post that is planned
* Update kea.isc.org
* Update Wikipedia page release info
* Add new hooks to downloadable products (if applies)
* Update subscription data sheet with any new hook (if applies)
* Inform sales about what the release may mean to them
- [ ] 13. Check KnownIssues list on kea.isc.org https://kea.isc.org/wiki/KeaKnownIssues
- ssh kea.isc.org /var/www/kea-docs
- [ ] 14. update page: https://wiki.isc.org/bin/view/Main/KeaReleaseDates
- [ ] 15. update page: https://wiki.isc.org/bin/view/Main/EngineeringReleaseSchedule
AUTHORS
View file @ ac0bbcf6
......@@ -5,16 +5,24 @@ Primary developers:
- Tomek Mrugalski (lead developer: DHCPv4, DHCPv6 components, prefix
delegation, memfile, database interface, core libdhcp++,
host reservation, MAC extraction in DHCPv6,
statistics manager, kea-shell)
statistics manager, kea-shell, netconf, flex/bison
parsers, flex-id, documentation)
- Stephen Morris (Hooks, MySQL)
- Marcin Siodelski (DHCPv4, DHCPv6 components, options handling, perfdhcp,
host reservation, lease file cleanup, lease expiration,
control agent, shared networks, high availability)
- Thomas Markwalder (DDNS, user_chk, global host reservations)
control agent, shared networks, high availability,
config backend)
- Thomas Markwalder (DDNS, user_chk, global host reservations, stat commands,
congestion handling, config backend)
- Jeremy C. Reed (documentation, build system, testing, release engineering)
- Wlodek Wencel (testing, release engineering)
- Francis Dupont (crypto, perfdhcp, control agent)
- Francis Dupont (crypto, flex/bison parsers, perfdhcp, control agent,
radius, netconf, config backend)
- Brian Reid (logo design)
- Shawn Routhier (lease file cleanup)
- Michal Nowikowski (testing, hammer, release engineering)
- Razvan Becheriu (cassandra, sysrepo)
- Suzanne Goldlust (documentation)
Primary area of work mentioned in parentheses. The list is in a roughly
chronological order.
......@@ -68,6 +76,8 @@ We have received the following contributions:
- Adam Osuchowski, Silesian University of Technology
2014-09: Examples corrected in Kea ARM
2019-02: Hooks installation directory fixed.
2019-02: Possible syntax error in keactrl fixed.
- Nicolas Chaigneau, Capgemini
2014-09: Fix for interfaces with multiple addresses in perfdhcp
......@@ -180,17 +190,15 @@ We have received the following contributions:
- Vicky Risk
2018-08: Documentation clean up
2018-10: API documentation clean ups
- Franciszek Gorski
2018-10: Makefile bug fixed
2019-07: Statistics enhancements
2019-09: Statistics initialization enhancements
Kea uses log4cplus (http://sourceforge.net/projects/log4cplus/) for logging,
Boost (http://www.boost.org/) library for almost everything, and can use Botan
(http://botan.randombit.net/) or OpenSSL (https://www.openssl.org/) for
cryptographic operations. It can also optionally use PostgreSQL
(http://www.postgresql.org/) and/or MySQL (http://www.mysql.com/) and/or
Cassandra (http://cassandra.apache.org/) as a database.
- Suzanne Goldlust
2018-10: API documentation
Kea can use googletest for unit-tests (https://github.com/google/googletest).
Kea uses ISC Forge (https://github.com/isc-projects/forge/) for conformance testing.
- lpaserati, Thorsten Krohn
2018-11: Two bugfixes in kea-admin
CONTRIBUTING.md 0 → 100644
View file @ ac0bbcf6
# Kea Contributor's Guide
So you found a bug in Kea or plan to develop an extension and want to send us a patch? Great! This
page will explain how to contribute your changes smoothly.
Here's a quick list of how to contribute a patch:
1. **create account** on [gitlab](https://gitlab.isc.org)
2. **open an issue** in [Kea project](https://gitlab.isc.org/isc-projects/kea/issues/new), make sure
it describes what you want to fix and **why**
3. **ask someone from the ISC team to give you permission to fork Kea** (ask @tomek, @vicky, @ondrej
or @godfryd or basically anyone from the Kea dev team)
4. **fork Kea code**: go to Kea project page, click [Fork button](https://gitlab.isc.org/isc-projects/kea/forks/new).
If you can't, you didn't complete step 3.
5. **Implement your fix or feature, push code** to your repo. Make sure it compiles, has unit-tests,
is documented and does what it's supposed to do.
6. **Open Merge Request**: go to Kea project [merge requests page](https://gitlab.isc.org/isc-projects/kea/merge_requests),
click [New merge request](https://gitlab.isc.org/isc-projects/kea/merge_requests/new). If you
don't see the button, you didn't complete step 3.
7. **Participate in the code review**: Once you submit the MR, someone from ISC will eventually get
to the issue and will review your code. Please make sure you respond to comments. It's likely
you'll be asked to update the code.
For a much more detailed description with details, see the text below.
## Writing a patch
Before you start working on a patch or a new feature, it is a good idea to discuss it first with Kea
developers. You can post your questions to the [kea-dev](https://lists.isc.org/mailman/listinfo/kea-dev)
or [kea-users](https://lists.isc.org/mailman/listinfo/kea-users) mailing lists. The kea-users is
intended for users who are not interested in the internal workings or development details of Kea: it
is OK to ask for feedback regarding new design or the best proposed solution to a certain
problem. This is the best place to get user's feedback. The internal details, questions about the
code and its internals are better asked on kea-dev.
OK, so you have written a patch? Great! Before you submit it, make sure that your code
compiles. This may seem obvious, but there's more to it. You have surely checked that it compiles on
your system, but Kea is a portable software. Besides Linux, it is compiled and used on relatively
uncommon systems like OpenBSD. Will your code compile and work there? What about endianness? It is
likely that you used a regular x86 architecture machine to write your patch, but the software is
expected to run on many other architectures. You may take a look at [system specific build
notes](https://kb.isc.org/docs/installing-kea). For a complete list of systems we build on, you may
take a look at the [Jenkins build farm](https://jenkins.isc.org/).
Does your patch conform to [Kea coding
guidelines](https://gitlab.isc.org/isc-projects/kea/wikis/coding-guidelines)? You can submit a
patch that does not adhere to them, but that will reduce its chances of being accepted. If the
deviations are minor, one of the Kea engineers who does the review will likely fix the issues.
However, if there are lots of issues, the reviewer may simply reject the patch and ask you to fix it
before re-submitting.
## Running unit-tests
One of the ground rules in Kea development is that every piece of code has to be tested. We now have
an extensive set of unit-tests for almost every line of code. Even if you are fixing something
small, like a single line fix, you are encouraged to write unit-tests for that change. That is even
more true for new code: if you write a new function, method or a class, you definitely should write
unit-tests for it.
To ensure that everything is tested, ISC uses a development method called [Test Driven Development
(TDD)](https://en.wikipedia.org/wiki/Test-driven_development). In TDD, a feature is developed
alongside the tests, preferably with the tests being written first. In detail, a test is written for
a small piece of functionality and run against the existing code. (In the case where the test is a
unit test for a function, it would be run against an empty (unimplemented) function.) The test
should fail. A minimal amount of code is then written, just enough to get the test to pass. Then
the process is repeated for the next small piece of functionality. This continues until all the
functionality has been implemented.
This approach has two advantages:
- By writing a test first and then only enough code to pass the test, that code is fully tested. By
repeating this process until the feature is fully implemented, all the code gets test
coverage. You avoid the situation where not enough tests have been written to check all the
code.
- By running the test before the code implementing the function is written and observing the test
fail, you can detect the situation where a bug in the test code will cause it to pass regardless
of the code being tested.
Initially, some people unfamiliar with that approach react with "but my change is simple and I
tested that it works". That approach is both insufficient and short-sighted. It is insufficient,
because manual testing is by definition laborious and can't really be done 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 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 hope to make Kea last similar time span. Over
such long periods, code tends to be refactored several times. The change you made may be affected by
some other change or by the code that hasn't been written yet.
See Building Kea with Unit Tests for instructions on how to run unit-tests. If you happen to touch
any database related code, make sure you compile your code with –with-mysql, –with-pgsql and/or
–with-cql as needed. For example, if you change something substantial, make sure the other
compilation options still work.
If you happen to add new files or have modified any Makefile.am files, it is also a good idea to
check if you haven't broken the distribution process:
```bash
make distcheck
```
There are other useful switches which can be passed to configure. It is always a good idea to use
`–enable-logger-checks`, which does sanity checks on logger parameters. Use `–-enable-debug` to
enable various additional consistency checks that reduce performance but help during development. If
you happen to modify anything in the documentation, use `–-enable-generate-docs`. If you are
modifying DHCP code, you are likely to be interested in enabling a non-default database backends for
DHCP. Note that if the backend is not enabled, the database-specific unit-tests are skipped. To
enable the MySQL backend, use the switch `–with-mysql`; for PostgreSQL, use `–with-pgsql` and for
Cassandra use `--with-cql`. A complete list of all switches can be obtained with the command:
```bash
./configure --help
```
## Submitting Merge Request (also known as sending your patch the right way)
The first step in writing the patch or new feature should be to get the source code from our Git
repository. The procedure is very easy and is [explained
here](https://gitlab.isc.org/isc-projects/kea/wikis/processes/gitlab-howto). While it is possible
to provide a patch against the latest stable release, it makes the review process much easier if it
is for latest code from the Git master branch.
ISC uses [gitlab](https://gitlab.isc.org) to manage its source code. While we also maintain presence
on [github](https://github.com/isc-projects/kea), the process of syncing gitlab to github is mostly
automated and Kea devs rarely look at github.
ISC's gitlab has been a target for spammers in the past, so it is now set up defensively. In
particular, new users can't fork the code on their own and it requires someone from ISC to manually
grant the ability to fork projects. Fortunately, this is easy to do and we glady do this for anyone
who asks and provides a good reason. "I'd like to fix bug X or develop feature Y" is an excellent
reason. The best place for asking is either kea-dev or asking in a comment in your issue. Make sure
you put a name tag (@tomek, @godfryd, @vicky or @ondrej). When you write a comment in an issue or
merge request and add a name tag on it, the user is automatically notified.
Once you fork the Kea code in gitlab, you have your own copy and you can commit your changes there
and push them to your copy of Kea repo. Once you feel that your patch is ready, go to Kea project
and [submit a Merge Request](https://gitlab.isc.org/isc-projects/kea/merge_requests/new).
If you can't access this link or don't see New Merge Request button on the [merge requests
page](https://gitlab.isc.org/isc-projects/kea/merge_requests), please ask on kea-dev and someone
will help you out.
## Send Pull Request on github
If you can't send the patch on gitlab, the next best preferred way is to send pull request (PR) on
[github](https://github.com/isc-projects/kea).
This is almost as good as sending MR on gitlab. The downside is that Kea devs don't look at github
too frequently, so it may be a while before we notice it. And when we do, the chances are we will be
busy with other things. With gitlab, your MR will stare at us the whole time, so we'll get round to
it much quicker. But we understand that there are some cases where people may prefer github over
gitlab.
See the excellent documentation on github: https://help.github.com/articles/creating-a-pull-request/
for details. In essence, you need github account (spam/hassle free, takes one minute to set
up). Then you can fork the Kea repository, commit changes to you