A big welcome and thank you for considering making a contribution to authd and Ubuntu! It’s people like you that help make these products a reality for users in our community.
By agreeing to follow these guidelines the contribution process should be easy and effective for everyone involved. This also communicates that you agree to respect the time of the developers working on this project. In return, we will reciprocate that respect by addressing your issues, assessing proposed changes and helping you finalise your pull requests.
These are mostly guidelines, not rules. Use your best judgement and feel free to propose changes to this document in a pull request.
- Contributing to authd
We take our community seriously, holding ourselves and other contributors to high standards of communication. By contributing to this project you agree to uphold the Ubuntu community Code of Conduct.
Contributions are made to this project via Issues and Pull Requests (PRs). These are some general guidelines that cover both:
- To report security vulnerabilities, use the advisories page of the repository and not a public bug report. Please use launchpad private bugs, which is monitored by our security team. On an Ubuntu machine, it’s best to use
ubuntu-bug authdto collect relevant information. - General issues or feature requests should be reported to the GitHub Project
- If you've never contributed before, see this post on ubuntu.com for resources and tips on how to get started.
- Existing Issues and PRs should be searched for on the project's repository before creating your own.
- While we work hard to ensure that issues are handled in a timely manner, it can take time to investigate the root cause. A friendly ping in the comment thread to the submitter or a contributor can help draw attention if your issue is blocking.
Issues can be used to report problems with the software, request a new feature or discuss potential changes before a PR is created. When you create a new Issue, a template will be loaded that will guide you through collecting and providing the information that we need to investigate.
If you find an Issue that addresses the problem you're having, please add your own reproduction information to the existing issue rather than creating a new one. Adding a reaction can also help be indicating to our maintainers that a particular problem is affecting more than just the reporter.
PRs to our project are always welcome and can be a quick way to get your fix or improvement slated for the next release. In general, PRs should:
- Only fix/add the functionality in question OR address wide-spread whitespace/style issues, not both.
- Add unit or integration tests for fixed or changed functionality.
- Address a single concern in the least possible number of changed lines.
- Include documentation in the repo or on our docs site.
- Be accompanied by a complete Pull Request template (loaded automatically when a PR is created).
For changes that address core functionality or that would require breaking changes (e.g. a major release), it's best to open an Issue to discuss your proposal first. This is not required but can save time when creating and reviewing changes.
In general, we follow the "fork-and-pull" Git workflow:
- Fork the repository to your own Github account.
- Clone the fork to your machine.
- Create a branch locally with a succinct but descriptive name.
- Commit changes to that branch.
- Follow any formatting and testing guidelines specific to this repo.
- Push changes to your fork.
- Open a PR in our repository and follow the PR template so that we can efficiently review the changes.
PRs will trigger unit and integration tests with and without race detection, linting and formatting validations, static and security checks, and freshness of generated files verification. All these tests must pass before any merge into the main branch.
Once merged into the main branch, po files and any documentation change will be automatically updated. Updates to these files are therefore not necessary in the pull request itself, which helps minimise diff review.
This project has several build dependencies. You can install these dependencies from the top of the source tree using the apt command as follows:
sudo apt update
sudo apt build-dep .
sudo apt install devscriptsThe project consists of the following binaries:
authd: The main authentication service.pam_authd.so: A PAM native module (used by GDM).pam_authd_exec.so,authd-pam: A PAM module and its helper executable (used by other PAM applications).libnss_authd.so: An NSS module.
The project can be built as a Debian package. This process will compile all the binaries, run the test suite and produce the Debian packages.
Alternatively, for development purposes, each binary can be built manually and separately.
Building the Debian package from source is the most straightforward and standard method for compiling the binaries and running the test suite. To do this, run the following commands from the top of the source tree:
This is required to vendorize the Rust crates and must be done only once.
sudo apt install libssl-dev
cargo install cargo-vendor-filtererThen build the Debian package:
debuild --prepend-path=${HOME}/.cargo/binThe Debian packages are available in the parent directory.
To build authd only, run the following command from the top of the source tree:
go build ./cmd/authdThe built binary will be found in the current directory. The daemon can be run directly from this binary without installing it on the system.
To build the PAM module, from the top of the source tree run the following commands:
Note
This command installs the tooling to hook up the Go GRPC modules to protoc.
cd tools/
grep -o '_ ".*"' *.go | cut -d '"' -f 2 | xargs go install
cd ..Then build the PAM module:
go generate ./pam/
go build -tags pam_binary_exec -o ./pam/authd-pam ./pamThis last command will produce two libraries (./pam/pam_authd.so and ./pam/go-exec/pam_authd_exec.so) and an executable (./pam/authd-pam).
These modules must be copied to /usr/lib/$(gcc -dumpmachine)/security/ while the executable must be copied to /usr/libexec/authd-pam.
For further information about the PAM module architecture and testing see the PAM Hacking page.
To build the NSS module, from the top of the source tree run the command:
cargo buildThis will build a debug release of the NSS module.
The library resulting from the build is located in ./target/debug/libnss_authd.so. This module must be copied to /usr/lib/$(gcc -dumpmachine)/libnss_authd.so.2.
The project includes a comprehensive test suite made of unit and integration tests. All the tests must pass before the review is considered. If you have troubles with the test suite, feel free to mention it in your PR description.
You can run all tests with: go test ./... (add the -race flag for race detection).
Every package has a suite of at least package-level tests. They may integrate more granular unit tests for complex functionalities. Integration tests are located in ./pam/integration-tests for the PAM module and ./nss/integration-tests for the NSS module.
The test suite must pass before merging the PR to our main branch. Any new feature, change or fix must be covered by corresponding tests.
Some tests, such as the PAM CLI tests, use external tools such as vhs to record and run the tape files needed for the tests. Those tools are not included in the project dependencies and must be installed manually.
Information about these tools and their usage will be linked below:
- vhs: tutorial on using vhs as a CLI-based video recorder
This project follow the Go code-style. For more detailed information about the code style in use, please check https://google.github.io/styleguide/go/.
It is a requirement that you sign the Contributor License Agreement in order to contribute to this project. You only need to sign this once and if you have previously signed the agreement when contributing to other Canonical projects you will not need to sign it again.
An automated test is executed on PRs to check if this agreement has been accepted.
Join us in the Ubuntu Community and post your question there with a descriptive tag.