diff --git a/Makefile b/Makefile index 58ceca64..a48da6d0 100644 --- a/Makefile +++ b/Makefile @@ -69,7 +69,7 @@ deb: rpm: mkdir -p ./packaging/ git submodule init; git submodule update - for v in rocky8 rocky9 tumbleweed; do \ + for v in rocky8 rocky9 sle15sp6 tumbleweed rawhide fedora41; do \ echo "Building $$v RPM packages"; \ $(DOCKER) build -t himmelblau-$$v-build -f images/rpm/Dockerfile.$$v .; \ $(DOCKER) run --rm -it -v ./:/himmelblau himmelblau-$$v-build; \ diff --git a/images/rpm/Dockerfile.fedora41 b/images/rpm/Dockerfile.fedora41 new file mode 100644 index 00000000..5bea78f7 --- /dev/null +++ b/images/rpm/Dockerfile.fedora41 @@ -0,0 +1,40 @@ +# Use the official Fedora 41 image as the base +FROM fedora:41 + +# Update the package list and install essential build dependencies +RUN dnf -y update && \ + dnf -y install \ + wget \ + git \ + gcc \ + gcc-c++ \ + make \ + openssl-devel \ + dbus-devel \ + libtool \ + pkg-config \ + autoconf \ + pam-devel \ + systemd-devel \ + krb5-devel \ + pcre2-devel \ + clang \ + gettext \ + sqlite-devel \ + utf8proc-devel \ + cargo && \ + dnf clean all + +# Set environment for Rust +ENV PATH="/root/.cargo/bin:${PATH}" + +VOLUME /himmelblau + +# Change directory to the repository +WORKDIR /himmelblau + +# Install the cargo-deb tool +RUN cargo install cargo-generate-rpm + +# Build the project and create the RPM package +CMD cargo clean && cargo build --release && strip -s target/release/*.so && strip -s target/release/aad-tool && strip -s target/release/himmelblaud && strip -s target/release/himmelblaud_tasks && strip -s target/release/broker && cargo generate-rpm -p src/daemon && cargo generate-rpm -p src/nss && cargo generate-rpm -p src/pam && cargo generate-rpm -p src/sshd-config diff --git a/images/rpm/Dockerfile.rawhide b/images/rpm/Dockerfile.rawhide new file mode 100644 index 00000000..0c877b5a --- /dev/null +++ b/images/rpm/Dockerfile.rawhide @@ -0,0 +1,40 @@ +# Use the official Fedora Rawhide image as the base +FROM fedora:rawhide + +# Update the package list and install essential build dependencies +RUN dnf -y update && \ + dnf -y install \ + wget \ + git \ + gcc \ + gcc-c++ \ + make \ + openssl-devel \ + dbus-devel \ + libtool \ + pkg-config \ + autoconf \ + pam-devel \ + systemd-devel \ + krb5-devel \ + pcre2-devel \ + clang \ + gettext \ + sqlite-devel \ + utf8proc-devel \ + cargo && \ + dnf clean all + +# Set environment for Rust +ENV PATH="/root/.cargo/bin:${PATH}" + +VOLUME /himmelblau + +# Change directory to the repository +WORKDIR /himmelblau + +# Install the cargo-deb tool +RUN cargo install cargo-generate-rpm + +# Build the project and create the RPM package +CMD cargo clean && cargo build --release && strip -s target/release/*.so && strip -s target/release/aad-tool && strip -s target/release/himmelblaud && strip -s target/release/himmelblaud_tasks && strip -s target/release/broker && cargo generate-rpm -p src/daemon && cargo generate-rpm -p src/nss && cargo generate-rpm -p src/pam && cargo generate-rpm -p src/sshd-config diff --git a/images/rpm/Dockerfile.sle15sp6 b/images/rpm/Dockerfile.sle15sp6 new file mode 100644 index 00000000..0329dec9 --- /dev/null +++ b/images/rpm/Dockerfile.sle15sp6 @@ -0,0 +1,41 @@ +# Use the official openSUSE Leap 15.6 image as the base +FROM opensuse/leap:15.6 + +# Update the package list and install essential build dependencies +RUN zypper --non-interactive refresh && zypper --non-interactive update && \ + zypper --non-interactive install --no-recommends \ + wget \ + git \ + gcc \ + gcc-c++ \ + make \ + libopenssl-3-devel \ + dbus-1-devel \ + libtool \ + pkg-config \ + autoconf \ + pam-devel \ + systemd-devel \ + libcap-progs \ + krb5-devel \ + pcre2-devel \ + clang \ + gettext-tools \ + sqlite3-devel \ + utf8proc-devel \ + cargo \ + && zypper clean --all + +# Set environment for Rust +ENV PATH="/root/.cargo/bin:${PATH}" + +VOLUME /himmelblau + +# Change directory to the repository +WORKDIR /himmelblau + +# Install the cargo-deb tool +RUN cargo install cargo-generate-rpm + +# Build the project and create the RPM package +CMD cargo clean && cargo build --release && strip -s target/release/*.so && strip -s target/release/aad-tool && strip -s target/release/himmelblaud && strip -s target/release/himmelblaud_tasks && strip -s target/release/broker && cargo generate-rpm -p src/daemon && cargo generate-rpm -p src/nss && cargo generate-rpm -p src/pam && cargo generate-rpm -p src/sshd-config diff --git a/man/man5/himmelblau.conf.5 b/man/man5/himmelblau.conf.5 new file mode 100644 index 00000000..9215a1e2 --- /dev/null +++ b/man/man5/himmelblau.conf.5 @@ -0,0 +1,352 @@ +.TH HIMMELBLAU.CONF "5" "November 2024" "Himmelblau Configuration" "File Formats" +.SH NAME +himmelblau.conf \- Configuration file for Himmelblau, enabling Azure Entra ID authentication on Linux. + +.SH SYNOPSIS +.B /etc/himmelblau/himmelblau.conf + +.SH HOW CONFIGURATION CHANGES ARE APPLIED +Changes to the configuration file +.B /etc/himmelblau/himmelblau.conf +only take effect after restarting the Himmelblau daemons. This includes the +.B himmelblaud +daemon, which handles authentication, and the +.B himmelblaud-tasks +daemon, which processes related tasks. + +.TP +.B Restarting the Daemons +To apply changes, restart the Himmelblau services using the following systemd commands: + +.EXAMPLES +.RS +.IP +sudo systemctl restart himmelblaud +.IP +sudo systemctl restart himmelblaud-tasks +.RE + +.SH DESCRIPTION +The +.B himmelblau.conf +file is the primary configuration file for the Himmelblau authentication module. It defines global and optional settings required for Azure Entra ID-based authentication and device management. + +.SH FILE FORMAT +The file consists of sections headed by a name enclosed in square brackets. Each section contains parameters and their values in the format: +.RS 4 +parameter = value +.RE + +Lines beginning with a '#' are comments and are ignored by the parser. + +.SH PARAMETERS + +.SS [global] +This section contains settings that apply globally to all operations of Himmelblau. + +.TP +.B domains +.RE +A comma-separated list of configured domains. This parameter is +.B REQUIRED +for successful authentication. If this option is not specified, no users will be permitted to authenticate. The first user to authenticate to each domain will become the owner of the device object in the directory. + +.EXAMPLES +domains = example.com,example2.com + +.TP +.B debug +.RE +A boolean option that enables debug-level logging. When set to +.B true, +debug messages are output to the system journal. + +.EXAMPLES +debug = true + +.TP +.B pam_allow_groups +.RE +A comma-separated list of Users and Groups permitted to access the system. Groups must be specified using their Object ID (not UPN) due to Azure's restrictions on reading group names. + +.EXAMPLES +pam_allow_groups = f3c9a7e4-7d5a-47e8-832f-3d2d92abcd12,d98c8e1d-7f8a-4597-babc-9d3b781ef456 + +.TP +.B id_attr_map +.RE +Specifies whether to map user and group IDs based on the object name or object UUID. Mapping by name is recommended for more consistent SSH authentication. + +.EXAMPLES +id_attr_map = + +.TP +.B odc_provider +.RE +Specifies the hostname for sending federationProvider requests. + +.EXAMPLES +odc_provider = odc.officeapps.live.com + +.TP +.B enable_hello +.RE +Enables or disables user enrollment in Windows Hello authentication. If disabled, users will need to provide MFA for each login. + +.EXAMPLES +enable_hello = false + +.TP +.B hello_pin_min_length +.RE +The minimum length of the PIN for Windows Hello authentication. The value must be between 6 and 32 characters. + +.EXAMPLES +hello_pin_min_length = 8 + +.TP +.B enable_sfa_fallback +.RE +Determines whether password-only (single-factor) authentication is permitted when MFA is unavailable. Disabled by default. + +.EXAMPLES +enable_sfa_fallback = true + +.TP +.B cn_to_upn_mapping +.RE +Allows users to enter the short form of their username (e.g., 'dave') instead of the full UPN. + +.EXAMPLES +cn_to_upn_mapping = true + +.TP +.B local_groups +.RE +A comma-separated list of local groups that every Entra ID user should be a member of. For example, you may wish for all Entra ID users to be a member of the sudo group. WARNING: This setting will not REMOVE group member entries when groups are removed from this list. You must remove them manually. + +.EXAMPLES +local_groups = sudo,admin + +.TP +.B logon_script +.RE +A script that will execute every time a user logs on. Two environment variables are set: USERNAME, and ACCESS_TOKEN. The ACCESS_TOKEN environment variable is an access token for the MS Graph. The token scope config option sets the comma-separated scopes that should be requested for the ACCESS_TOKEN. ACCESS_TOKEN will be empty during offline logon. The return code of the script determines how authentication proceeds. 0 is success, 1 is a soft failure and authentication will proceed, while 2 is a hard failure causing authentication to fail. + +.EXAMPLES +logon_script = /etc/himmelblau/logon.sh + +.TP +.B logon_token_scopes +.RE +A comma-separated list of the scopes to be requested for the ACCESS_TOKEN during logon. + +.EXAMPLES +logon_token_scopes = user.read,mail.read + +.TP +.B authority_host +.RE +Specifies the hostname for Microsoft authentication. The default value is +.B login.microsoftonline.com. + +.EXAMPLES +authority_host = login.microsoftonline.com + +.TP +.B db_path +.RE +The location of the cache database. This file is used to store cached authentication data and device state. + +.EXAMPLES +db_path = /var/cache/himmelblau/himmelblau.cache.db + +.TP +.B hsm_pin_path +.RE +The location where the HSM (Hardware Security Module) PIN will be stored. This PIN is used to protect sensitive cryptographic operations. + +.EXAMPLES +hsm_pin_path = /var/lib/himmelblaud/hsm-pin + +.TP +.B socket_path +.RE +The path to the socket file for communication between the pam and nss modules and the Himmelblau daemon. + +.EXAMPLES +socket_path = /var/run/himmelblaud/socket + +.TP +.B task_socket_path +.RE +The path to the socket file for communication with the task daemon. + +.EXAMPLES +task_socket_path = /var/run/himmelblaud/task_sock + +.TP +.B broker_socket_path +.RE +The path to the socket file for communication with the broker DBus service. + +.EXAMPLES +broker_socket_path = /var/run/himmelblaud/broker_sock + +.TP +.B home_prefix +.RE +The prefix to use for user home directories. + +.EXAMPLES +home_prefix = /home/ + +.TP +.B home_attr +.RE +The attribute used to create a home directory for a user. Available options include: +.RS +.IP +\- UUID (default) +.IP +\- SPN +.IP +\- CN +.RE + +.EXAMPLES +home_attr = UUID + +.TP +.B home_alias +.RE +The symlinked alias for the user's home directory. Available options include: +.RS +.IP +\- UUID +.IP +\- SPN (default) +.IP +\- CN +.RE + +.EXAMPLES +home_alias = SPN + +.TP +.B shell +.RE +The default shell for users. This will be assigned when the user logs in. + +.EXAMPLES +shell = /bin/bash + +.TP +.B idmap_range +.RE +Specifies the range of IDs to be used for the user and group mappings. + +.EXAMPLES +idmap_range = 5000000-5999999 + +.TP +.B connection_timeout +.RE +The timeout for connections to the authentication server. Default is 2 seconds. + +.EXAMPLES +connection_timeout = 5 + +.TP +.B cache_timeout +.RE +The timeout for caching authentication data. Default is 15 seconds. + +.EXAMPLES +cache_timeout = 10 + +.TP +.B use_etc_skel +.RE +If set to +.B true, +Himmelblau will use the contents of /etc/skel when creating new user directories. + +.EXAMPLES +use_etc_skel = false + +.TP +.B selinux +.RE +Whether SELinux security labels should be applied to users' home directories. Set to +.B true +to enable. + +.EXAMPLES +selinux = true + +.SH DOMAIN-SPECIFIC SECTIONS +Overrides can be defined for individual domains by using a section named after the domain in square brackets. + +.SS [example.com] +This section allows customization of specific parameters for the domain +.B example.com. +Domain-specific sections override global values for the specified domain. + +.TP +.B odc_provider +.RE +Overrides the `odc_provider` value for this domain. + +.EXAMPLES +[example.com] +odc_provider = custom.odcprovider.example.com + +.TP +.B home_prefix +.RE +Overrides the `home_prefix` value for this domain. + +.EXAMPLES +[example.com] +home_prefix = /home/ + +.TP +.B home_attr +.RE +Overrides the `home_attr` value for this domain. + +.EXAMPLES +[example.com] +home_attr = UUID + +.TP +.B home_alias +.RE +Overrides the `home_alias` value for this domain. + +.EXAMPLES +[example.com] +home_alias = SPN + +.TP +.B shell +.RE +Overrides the `shell` value for this domain. + +.EXAMPLES +[example.com] +shell = /bin/bash + +.TP +.B idmap_range +.RE +Overrides the `idmap_range` value for this domain. + +.EXAMPLES +[example.com] +idmap_range = 5000000-5999999 + +.SH SEE ALSO +.BR himmelblaud(8), +.BR himmelblaud-tasks(8) diff --git a/man/man8/himmelblaud.8 b/man/man8/himmelblaud.8 index c2b47295..2f047bd4 100644 --- a/man/man8/himmelblaud.8 +++ b/man/man8/himmelblaud.8 @@ -48,7 +48,6 @@ Print the version of the `himmelblaud` daemon and exit. .TP .B Enable debug mode: # himmelblaud --debug -.SH "SEE ALSO" -Documentation for the `himmelblaud` daemon is available in the Texinfo manual. Use the following command to access the full manual: -.BR info himmelblaud +.SH SEE ALSO +.BR himmelblaud-tasks(8) diff --git a/man/man8/himmelblaud_tasks.8 b/man/man8/himmelblaud_tasks.8 index e150439d..6a2526c2 100644 --- a/man/man8/himmelblaud_tasks.8 +++ b/man/man8/himmelblaud_tasks.8 @@ -4,26 +4,24 @@ himmelblaud_tasks \- Home directory creation daemon for Himmelblau .SH SYNOPSIS .B himmelblaud_tasks .SH DESCRIPTION -The `himmelblaud_tasks` daemon is responsible for automatically creating home directories for users upon successful authentication via Azure Entra ID. This service is required to run as the root user, as it needs elevated permissions to create directories in system locations. +The `himmelblaud-tasks` daemon is responsible for managing user accounts and authentication tasks in a Linux environment. Upon successful authentication via Azure Entra ID, it automatically creates home directories for users, adds them to configured local groups, executes the configured logon script, and handles the caching of Kerberos ccache files. This service requires root privileges to perform actions such as creating directories in system locations and managing group memberships. The daemon operates as a background service and does not accept any command-line arguments. It is automatically invoked by the system when required. .SH USAGE -The `himmelblaud_tasks` daemon must be run as the root user. If the daemon is started without root privileges, it will fail with an error. No user interaction is needed beyond ensuring the daemon is active and running correctly. +The `himmelblaud-tasks` daemon must be run as the root user. If the daemon is started without root privileges, it will fail with an error. No user interaction is needed beyond ensuring the daemon is active and running correctly. .SH EXAMPLES .TP .B Start the daemon: -# systemctl start himmelblaud_tasks +# systemctl start himmelblaud-tasks .TP .B Verify the status of the daemon: -# systemctl status himmelblaud_tasks +# systemctl status himmelblaud-tasks .SH NOTES -This daemon is integral to Himmelblau for handling user home directory creation. It ensures that users can properly log in with a valid directory structure in place after authentication. +This daemon is a key component of Himmelblau, handling several critical tasks for user authentication. In addition to creating user home directories, it adds users to the configured local groups, executes the configured logon script, and manages the caching of Kerberos ccache files. These functions ensure that users have the necessary environment and access rights in place for a seamless login experience after authentication. -.SH "SEE ALSO" -Further documentation for `himmelblaud_tasks` is available in the Texinfo manual. Use the following command to access the complete manual: - -.BR info himmelblaud_tasks +.SH SEE ALSO +.BR himmelblaud(8), diff --git a/src/daemon/Cargo.toml b/src/daemon/Cargo.toml index f2a01f1d..cc6aef38 100644 --- a/src/daemon/Cargo.toml +++ b/src/daemon/Cargo.toml @@ -59,6 +59,10 @@ assets = [ ["target/release/himmelblaud_tasks", "usr/sbin/", "755"], ["target/release/broker", "usr/sbin/", "755"], ["../../README.md", "usr/share/doc/himmelblau/README", "644"], + ["../../man/man1/aad-tool.1", "usr/share/man/man1/", "644"], + ["../../man/man5/himmelblau.conf.5", "usr/share/man/man5/", "644"], + ["../../man/man8/himmelblaud.8", "usr/share/man/man8/", "644"], + ["../../man/man8/himmelblaud_tasks.8", "usr/share/man/man8/", "644"], ] [package.metadata.generate-rpm] @@ -75,6 +79,10 @@ assets = [ { source = "target/release/himmelblaud_tasks", dest = "/usr/sbin/", mode = "755" }, { source = "target/release/broker", dest = "/usr/sbin/", mode = "755" }, { source = "../../README.md", dest = "/usr/share/doc/himmelblau/README", mode = "644" }, + { source = "../../man/man1/aad-tool.1", dest = "/usr/share/man/man1/", mode = "644" }, + { source = "../../man/man5/himmelblau.conf.5", dest = "/usr/share/man/man5/", mode = "644" }, + { source = "../../man/man8/himmelblaud.8", dest = "/usr/share/man/man8/", mode = "644" }, + { source = "../../man/man8/himmelblaud_tasks.8", dest = "/usr/share/man/man8/", mode = "644" }, ] [package.metadata.generate-rpm.recommends]