sonic-net · martin-belanger · Oct 6, 2020 · Nov 4, 2020 · Dec 4, 2020 · Dec 4, 2020
@@ -0,0 +1,9 @@
+DEP_FILES   := $(SONIC_COMMON_FILES_LIST) rules/ham.mk rules/ham.dep
+DEP_FILES   += $(SONIC_COMMON_BASE_FILES_LIST)
+
+$(SONIC_HAMD)_CACHE_MODE  := GIT_CONTENT_SHA
+$(SONIC_HAMD)_DEP_FLAGS   := $(SONIC_COMMON_FLAGS_LIST)
+$(SONIC_HAMD)_DEP_FILES   := $(DEP_FILES)
+$(SONIC_HAMD)_SMDEP_FILES := $(SMDEP_FILES)
+$(SONIC_HAMD)_SMDEP_PATHS := $(SPATH)
+
@@ -0,0 +1,21 @@
+HAM_VERSION := 1.0.0
+
+# Main package
+HAM = ham_$(HAM_VERSION)_$(CONFIGURED_ARCH).deb
+$(HAM)_SRC_PATH = $(SRC_PATH)/ham
+$(HAM)_DEPENDS  = $(LIBSWSSCOMMON_DEV)
+$(HAM)_RDEPENDS = $(LIBSWSSCOMMON)
+
+SONIC_DPKG_DEBS += $(HAM)
+
+# Additional packages
+LIBHAM_DEV = libham-dev_$(HAM_VERSION)_$(CONFIGURED_ARCH).deb
+LIBHAM     = libham_$(HAM_VERSION)_$(CONFIGURED_ARCH).deb
+LIBNSS_HAM = libnss-ham_$(HAM_VERSION)_$(CONFIGURED_ARCH).deb
+LIBNSS_SAC = libnss-sac_$(HAM_VERSION)_$(CONFIGURED_ARCH).deb
+
+$(eval $(call add_derived_package,$(HAM),$(LIBHAM_DEV)))
+$(eval $(call add_derived_package,$(HAM),$(LIBHAM)))
+$(eval $(call add_derived_package,$(HAM),$(LIBNSS_HAM)))
+$(eval $(call add_derived_package,$(HAM),$(LIBNSS_SAC)))
+
@@ -271,6 +271,8 @@ RUN apt-get update && apt-get install -y \
 # For initramfs
         shellcheck \
         bash-completion \
+# For HAM
+        libdbus-c++-dev \
 {%- if CONFIGURED_ARCH == "amd64" %}
 # For sonic vs image build
         dosfstools \

@@ -263,6 +263,8 @@ RUN apt-get update && apt-get install -y \
         texi2html \
 # For initramfs
         bash-completion \
+# For HAM
+        libdbus-c++-dev \
 {%- if CONFIGURED_ARCH == "amd64" %}
 # For sonic vs image build
         dosfstools \

@@ -0,0 +1,7 @@
+*.d
+*.o
+*.so
+*.so.2
+*.dbus-proxy.h
+*.dbus-adaptor.h
+hamd/hamd
@@ -0,0 +1,44 @@
+.ONESHELL:
+.SHELLFLAGS += -e
+
+TOPDIR   := $(abspath .)
+INSTALL  := /usr/bin/install
+SUB-DIRS := $(dir $(wildcard $(addsuffix /Makefile,$(shell find * -maxdepth 0 -type d | sort ))))
+
+
+.PHONY: all
+all:
+	@for dir in ${SUB-DIRS}; do \
+       make -C $${dir}; \
+    done
+
+
+.PHONY: install
+install:
+	rsync --archive --verbose --no-owner --no-group $(TOPDIR)/hamd/etc $(DESTDIR)
+	rsync --archive --verbose --no-owner --no-group $(TOPDIR)/libham/usr $(DESTDIR)
+
+    # Create destination directories
+	$(INSTALL) -d $(DESTDIR)/usr/sbin/
+	$(INSTALL) -d $(DESTDIR)/usr/bin/
+	$(INSTALL) -d $(DESTDIR)/lib/x86_64-linux-gnu/       # NSS libraries MUST be under /lib and NOT /usr/lib
+	$(INSTALL) -d $(DESTDIR)/usr/lib/x86_64-linux-gnu/
+
+    # Copy files over to newly created directories
+	$(INSTALL) -D $(TOPDIR)/hamd/hamd                  $(DESTDIR)/usr/sbin/.
+	$(INSTALL) -D $(TOPDIR)/hamctl/hamctl              $(DESTDIR)/usr/bin/.
+	$(INSTALL) -D $(TOPDIR)/libham/libham.so           $(DESTDIR)/usr/lib/x86_64-linux-gnu/.
+	$(INSTALL) -D $(TOPDIR)/libnss_ham/libnss_ham.so.2 $(DESTDIR)/lib/x86_64-linux-gnu/.
+	$(INSTALL) -D $(TOPDIR)/libnss_sac/libnss_sac.so.2 $(DESTDIR)/lib/x86_64-linux-gnu/.
+
+
+.PHONY: clean
+clean:
+	@for dir in ${SUB-DIRS}; do \
+       make -C $${dir} clean; \
+    done
+
+.PHONY: cleanall
+cleanall:
+	git clean -fdx
+
@@ -0,0 +1,66 @@
+# Host Account Management
+
+## Introduction
+
+Host Account Management, or HAM, serves as the single source of truth for SONiC user accounts. HAM was created to solve several problems related to user accounts. Here's a summary:
+
+- Allow applications running in containers to retrieve user account information on the host using standard APIs such as `getpwnam()`, `getgrname()`, etc.
+- Allow applications running in containers to create/modify/delete local user accounts on the host.
+- Automatically assign UNIX user credentials (UID/GID) for users authenticated by RADIUS/TACACS+ that do not natively provide UNIX credentials. 
+- Allow additional credentials (such as keys or certificates) to be automatically created when a new user account is created.
+
+HAM was introduced in [AAA Improvements](https://github.com/Azure/SONiC/blob/master/doc/aaa/AAA%20Improvements/AAA%20Improvements.md). This document lists several challenges related to AAA (Authentication, Authorization, and Accounting) and how HAM helps mitigate some of these problems. This document provides details about the HAM software.
+
+## Components
+
+HAM provides the following components.
+
+| Package                       | Description                                                  |
+| ----------------------------- | ------------------------------------------------------------ |
+| `ham_[ver]_[arch].deb`        | Contains `hamd`, the HAM daemon, and `hamctl` a companion utility program for `hamd`. |
+| `libham_[ver]_[arch].deb`     | Run-time library that primarily provides APIs to interact with `hamd` over D-Bus. |
+| `libham-dev_[ver]_[arch].deb` | The counterpart development library to `libham_[version]_[arch].deb` |
+| `libnss-ham_[ver]_[arch].deb` | NSS module that allows containerized apps to access user accounts on the host. |
+| `libnss-sac_[ver]_[arch].deb` | NSS module for System-Assigned Credential                    |
+
+## HAM Daemon (`hamd`)
+
+The HAM daemon, `hamd`, is managed by `systemd`. The following `systemctl` commands are supported:
+
+| Command                          | Description                                 |
+| -------------------------------- | ------------------------------------------- |
+| `systemctl start hamd.service`   | Start `hamd`                                |
+| `systemctl stop hamd.service`    | Stop `hamd`                                 |
+| `systemctl restart hamd.service` | Restart `hamd`. Effectively a stop + start. |
+| `systemctl reload hamd.service`  | Reload configuration.                       |
+
+### Configuration file
+
+`hamd`'s configuration file is: `/etc/sonic/hamd/config`. This file can be modified while the daemon is running. The reload command described above can be issued to reload the configuration while the daemon is running.
+
+The configuration file content is self-documented (look in the file to see which parameters are configurable).
+
+### D-Bus interface
+
+The interface to `hamd` is D-Bus. The D-Bus introspect method should be called to determine what APIs are available. The D-Bus interface is defined by the IDL (interface description language) file: [org.SONiC.HostAccountManagement.xml](./shared/org.SONiC.HostAccountManagement.xml).
+
+#### D-Bus security
+
+Many of the D-Bus APIs are restricted. Some are restricted to `root` only, others are restricted to groups `hamd_accounts` and `hamd`. The security policy can be found in `/etc/dbus-1/system.d/org.SONiC.HostAccountManagement.conf`.
+
+## The hamctl utility
+
+This is a shell utility designed for "human" users. It should not be invoked by other programs. It is a companion program to `hamd`. The `hamctl` utility is mainly used for debugging purposes. It is self-documented. Simply type "`hamctl --help`" for help.
+
+## Roles to group mapping
+
+It is possible to add users of a given role to specific Linux groups. For example, one may want to map users with "`admin`" role to the "`sudo`" group. The mapping can be defined in: `/etc/sonic/hamd/group-mapping`.
+
+## Application-specific credentials
+
+One can tell `hamd` to create supplemental user credentials with the use of plug-in scripts. For example, if one would like all new users created by `hamd` to automatically be assigned an SSH key, one need only add a script to the directory `/etc/sonic/hamd/scripts/post-create/`. Scripts added to this directory will be invoked, in asciibetical order, when users are created. Similarly, when users are deleted, `hamd` will invoke the scripts in `/etc/sonic/hamd/scripts/pre-delete/`. Note that when deleting a user account, `hamd` always deletes the whole home directory. So, it is not necessary to provide a "`/pre-delete`" to delete files from the home directory since those will be removed anyway. 
+
+The script syntax is defined in these two files.
+
+- `/etc/sonic/hamd/scripts/post-create/README`
+- `/etc/sonic/hamd/scripts/pre-delete/README`
@@ -0,0 +1,8 @@
+.debhelper/
+*.debhelper
+*.debhelper.log
+*.substvars
+tmp/
+files
+*/DEBIAN/*
+
@@ -0,0 +1,5 @@
+ham (1.0.0) stable; urgency=medium
+
+  * Initial release.
+
+ -- Martin Belanger <[email protected]>  Wed, 23 Sep 2020 10:50:00 -0400
@@ -0,0 +1 @@
+9
@@ -0,0 +1,58 @@
+Source: ham
+Maintainer: Martin Belanger <[email protected]>
+Build-Depends: debhelper (>= 8.0.0),
+               dh-systemd,
+               libdbus-c++-dev,
+               libglib2.0-dev,
+               pkg-config
+Vcs-Git: https://github.com/Azure/sonic-buildimage
+Homepage: https://azure.github.io/SONiC/
+Standards-Version: 3.9.3
+Section: net
+
+Package: ham
+Priority: extra
+Architecture: amd64
+Depends: libdbus-c++-1-0v5, libglib2.0-0, libhiredis0.14, ${shlibs:Depends}, ${misc:Depends}
+Description: SONiC Host Account Management
+ This package provides the daemon, hamd, which runs on the host and provides
+ user and group account management services. It allows applications running
+ in containers to retrieve account from the host. It can also allow users with
+ administrative privileges to create, modify, or delete user accounts on the
+ host. For example, an admin user running a CLI session in a container
+ could request hamd to create a new user account.
+
+Package: libnss-ham
+Priority: extra
+Architecture: amd64
+Depends: libdbus-c++-1-0v5, ${shlibs:Depends}, ${misc:Depends}
+Description: SONiC Host Account Management NSS module
+ The HAM NSS module allows applications running in containers to retrieve
+ host's user accounts (e.g. /etc/passwd, /etc/group, and /etc/shadow). To do
+ that, the NSS module contacts the HAM daemon (hamd) running on the host over
+ DBus. THIS PACKAGE IS MEANT TO BE INSTALLED IN CONTAINERS ONLY!
+
+Package: libnss-sac
+Priority: extra
+Architecture: amd64
+Depends: libdbus-c++-1-0v5, ${shlibs:Depends}, ${misc:Depends}
+Description: SONiC System Assigned Credentials NSS module
+ The SAC NSS module allows the automatic allocation of user credentials
+ when the standard methods (e.g. unix NSS module) fail to find credentials
+ for a user. This is to be used specifically by TACACS+ or RADIUS PAM modules
+ during user authentication.
+
+Package: libham
+Priority: extra
+Architecture: amd64
+Depends: libdbus-c++-1-0v5, ${shlibs:Depends}, ${misc:Depends}
+Description: SONiC Host Account Management NSS module
+ This library contains functions to talk to the HAM daemon over D-Bus.
+
+Package: libham-dev
+Priority: extra
+Architecture: amd64
+Depends: libham ${shlibs:Depends}, ${misc:Depends}
+Description: SONiC Host Account Management NSS module
+ This package provides the development headers to allow using library libham.so
+ provided by package libham.
@@ -0,0 +1,7 @@
+#!/usr/bin/make -f  
+%:  
+	dh $@ --with systemd
+
+
+override_dh_shlibdeps:
+	dh_shlibdeps --dpkg-shlibdeps-params=--ignore-missing-info -l$(shell pwd)/build/cli/target/.libs/:$(shell pwd)/build/cli/.libs/
@@ -0,0 +1,8 @@
+/etc/dbus-1/system.d/org.SONiC.HostAccountManagement.conf
+/etc/sonic/hamd/config
+/etc/sonic/hamd/group-mapping
+/etc/sonic/hamd/scripts/post-create/README
+/etc/sonic/hamd/scripts/pre-delete/README
+/lib/systemd/system/hamd.service
+/usr/sbin/hamd
+/usr/bin/hamctl