From f293a09f4651ba86f48a640acbd5196bc3c5db19 Mon Sep 17 00:00:00 2001 From: Jean-Baptiste Lallement Date: Wed, 3 Jul 2024 10:02:21 +0200 Subject: [PATCH 1/5] detailed where to report issues --- CONTRIBUTING.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 99cdc1063..2c81bc5ce 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -31,14 +31,15 @@ We take our community seriously and hold ourselves and other contributors to hig Contributions are made to this project via Issues and Pull Requests (PRs). A few general guidelines that cover both: -* To report security vulnerabilities, please use the advisories page of the repository and not a public bug report. Please use [launchpad private bugs](https://bugs.launchpad.net/ubuntu/+source/authd/+filebug) which is monitored by our security team. On ubuntu machine, it’s best to use `ubuntu-bug authd` to collect relevant information. FIXME: snap? -* Search for existing Issues and PRs on this repository before creating your own. +* To report security vulnerabilities, please use the advisories page of the repository and not a public bug report. Please use [launchpad private bugs](https://bugs.launchpad.net/ubuntu/+source/authd/+filebug) which is monitored by our security team. On ubuntu machine, it’s best to use `ubuntu-bug authd` to collect relevant information. +* General issues or feature requests should be reported to the [GitHub Project](https://github.com/ubuntu/authd/issues) +* Search for existing Issues and PRs on the [project's repository](https://github.com/ubuntu/authd) before creating your own. * We work hard to makes sure issues are handled in a timely manner but, depending on the impact, it could take a while 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. * If you've never contributed before, see [this Ubuntu discourse post](https://discourse.ubuntu.com/t/contribute/26) for resources and tips on how to get started. ### Issues -Issues should be used to report problems with the software, request a new feature, or to 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 we need to investigate. +Issues should be used to report problems with the software, request a new feature, or to discuss potential changes before a PR is created. When you [create a new Issue](https://github.com/ubuntu/authd/issues), a template will be loaded that will guide you through collecting and providing the information 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](https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/) can also help be indicating to our maintainers that a particular problem is affecting more than just the reporter. From f64831bef72d6e4a9f729f8cf9f1fad9cd8a1250 Mon Sep 17 00:00:00 2001 From: Jean-Baptiste Lallement Date: Wed, 3 Jul 2024 16:57:09 +0200 Subject: [PATCH 2/5] fixed the 'contribute to ubuntu' link --- CONTRIBUTING.md | 85 ++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 81 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2c81bc5ce..7efb7c1a7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -35,7 +35,7 @@ Contributions are made to this project via Issues and Pull Requests (PRs). A few * General issues or feature requests should be reported to the [GitHub Project](https://github.com/ubuntu/authd/issues) * Search for existing Issues and PRs on the [project's repository](https://github.com/ubuntu/authd) before creating your own. * We work hard to makes sure issues are handled in a timely manner but, depending on the impact, it could take a while 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. -* If you've never contributed before, see [this Ubuntu discourse post](https://discourse.ubuntu.com/t/contribute/26) for resources and tips on how to get started. +* If you've never contributed before, see [this post on ubuntu.com](https://ubuntu.com/community/contribute) for resources and tips on how to get started. ### Issues @@ -73,17 +73,94 @@ Once merged to the main branch, `po` files and any documentation change will be ### Required dependencies -TODO +This project has several build dependencies. You can install these dependencies from the top of the source tree using the `apt` command as follows: + +```shell +sudo apt update +sudo apt build-dep . +``` ### Building and running the binaries -TODO +The project consists of the following binaries: + +* `authd`: The main authentication service. +* `pam_authd.so` and `pam_authd_exec.so`: A PAM module and its helper library. +* `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 + +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 command from the top of the source tree: + +> [!NOTE] +> This is required to vendorize the Rust crates and must be only done once. +> ```shell +> sudo apt install libssl-dev +> cargo install cargo-vendor-filterer +> cargo vendor-filterer vendor_rust +> ``` + +Then build the Debian package: + +```shell +dpkg-buildpackage +``` + +The debian packages are available in the parent directory. + +#### Building authd only + +To build `authd` only, run the following command from the top of the source tree: + +```shell +go build ./cmd/authd +``` + +The built binary will be in the current directory. The daemon can be run directly from this binary without installing it on the system. + +#### Building the PAM module only + +To build the PAM module, from the top of the source tree run the following commands: + +> [!NOTE] +> This dependency is required to regenerate the proto files and is only needed once. +> ```shell +> sudo apt install protoc-gen-go +> ``` + +Then build the PAM module: + +```shell +go generate ./pam/ +``` + +This command will produce two binaries: `./pam/pam_authd.so` and `./pam/go-exec/pam_authd_exec.so`. + + These modules must be copied to `/usr/lib/x86_64-linux-gnu/security/pam_authd.so` and `/usr/lib/x86_64-linux-gnu/security/pam_authd_exec.so` respectively. + +#### Building the NSS module only + +To build the NSS module, from the top of the source tree run the command: + +```shell +cargo build +``` + +It 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/x86_64-linux-gnu/libnss_authd.so.2`. ### About the testsuite The project includes a comprehensive testsuite made of unit and integration tests. All the tests must pass before the review is considered. If you have troubles with the testsuite, feel free to mention it on your PR description. -TODO +You can run all tests with: `go test ./...` (add -race for race detection). + +Every packages have 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. From 604bab5f7ea779324b294353ec76e468fac0aba5 Mon Sep 17 00:00:00 2001 From: Jean-Baptiste Lallement Date: Thu, 4 Jul 2024 10:26:14 +0200 Subject: [PATCH 3/5] Apply suggestions from code review Add mention to authd-pam Co-authored-by: Marco Trevisan --- CONTRIBUTING.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7efb7c1a7..0c6e3d8e1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -85,7 +85,8 @@ sudo apt build-dep . The project consists of the following binaries: * `authd`: The main authentication service. -* `pam_authd.so` and `pam_authd_exec.so`: A PAM module and its helper library. +* `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. @@ -136,11 +137,12 @@ Then build the PAM module: ```shell go generate ./pam/ +go build -tags pam_binary_exec -o ./pam/authd-pam ./pam ``` -This command will produce two binaries: `./pam/pam_authd.so` and `./pam/go-exec/pam_authd_exec.so`. +This 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/x86_64-linux-gnu/security/pam_authd.so` and `/usr/lib/x86_64-linux-gnu/security/pam_authd_exec.so` respectively. +These modules must be copied to `/usr/lib/$(gcc -dumpmachine)/security/` while the executable must be copied to `/usr/libexec/authd-pam`. #### Building the NSS module only @@ -152,7 +154,7 @@ cargo build It 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/x86_64-linux-gnu/libnss_authd.so.2`. +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`. ### About the testsuite From 70b589352386576760416c7fea22cfece7c60ca8 Mon Sep 17 00:00:00 2001 From: Jean-Baptiste Lallement Date: Thu, 4 Jul 2024 14:18:38 +0200 Subject: [PATCH 4/5] Updated table of content --- CONTRIBUTING.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0c6e3d8e1..da6458db0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,6 +17,10 @@ These are mostly guidelines, not rules. Use your best judgment, and feel free to - [Contributing to the code](#contributing-to-the-code) - [Required dependencies](#required-dependencies) - [Building and running the binaries](#building-and-running-the-binaries) + - [Building the Debian package from source](#building-the-debian-package-from-source) + - [Building authd only](#building-authd-only) + - [Building the PAM module only](#building-the-pam-module-only) + - [Building the NSS module only](#building-the-nss-module-only) - [About the testsuite](#about-the-testsuite) - [Tests with dependencies](#tests-with-dependencies) - [Code style](#code-style) From 0b2d5d0863ed79fde72e9121c162c9ca33121fe2 Mon Sep 17 00:00:00 2001 From: Jean-Baptiste Lallement Date: Thu, 4 Jul 2024 14:19:26 +0200 Subject: [PATCH 5/5] updated build instructions --- CONTRIBUTING.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index da6458db0..384f306b3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -82,6 +82,7 @@ This project has several build dependencies. You can install these dependencies ```shell sudo apt update sudo apt build-dep . +sudo apt install devscripts ``` ### Building and running the binaries @@ -106,13 +107,12 @@ Building the Debian package from source is the most straightforward and standard > ```shell > sudo apt install libssl-dev > cargo install cargo-vendor-filterer -> cargo vendor-filterer vendor_rust > ``` Then build the Debian package: ```shell -dpkg-buildpackage +debuild --prepend-path=${HOME}/.cargo/bin ``` The debian packages are available in the parent directory. @@ -132,9 +132,11 @@ The built binary will be in the current directory. The daemon can be run directl To build the PAM module, from the top of the source tree run the following commands: > [!NOTE] -> This dependency is required to regenerate the proto files and is only needed once. +> This command installs the tooling to hook up the Go GRPC modules to protoc. > ```shell -> sudo apt install protoc-gen-go +> cd tools/ +> grep -o '_ ".*"' *.go | cut -d '"' -f 2 | xargs go install +> cd .. > ``` Then build the PAM module: