developer_guide Quick Start LDAP

This section contains a Quick Start developer_guide for the Secure PVAccess LDAP Authenticator.

The LDAP Authenticator is an Authenticator that creates an X.509 certificate from LDAP credentials.

It prompts the user to log in to the LDAP directory service. It then signs a certificate creation request with its private key and passes it to the PVACMS, which decodes it with the public key that it finds in the LDAP directory entry for the user. If this succeeds it means that the requester holds the matching private key and so the certificate is generated.

It uses the LDAP username as the common name and then concatenates all the dc components it finds to create the organisation while leaving the organizational unit blank. e.g. dn: uid=admin,dc=epics,dc=org becomes CN=admin, O=epics.org.

Our starting point for this Quick Start Guide is the end of the Quick Start Std so if you haven’t gone through it yet do that now then come back here. You need to have user’s configured (pvacms, admin, softioc, and client). We will set up a containerised LDAP Service and configure it so that the users can log in.

When to use the LDAP Authenticator?

  • Your network uses Kerberos for login

    If, as is normally the case, you use Kerberos for authentication and LDAP for user profile information - group, contact details, etc - then use the Kerberos Authenticator.

  • Your network clients login directly to LDAP

    If you’ve configured your LDAP server for user login then we will show how you could use LDAP login credentials to get an X.509 certificate.

See Secure PVAccess for general documentation on Secure PVAccess.

Other Quick Start Guides:

local_library You will learn:

deployed_codePrepackaged

If you want a prepackaged environment, try the following. You will need three terminal sessions.

counter_1 Load image

  • computer¹

  • start new container with Prepackaged Secure PVAccess with LDAP Authenticator and 4 Users

docker run -it --name spva_ldap georgeleveln/spva_ldap:latest

2025-03-08 19:53:45,557 CRIT Supervisor is running as root.  Privileges were not dropped because no user is specified in the config file.  If you intend to run as root, you can set user=root in the config file to avoid this message.
2025-03-08 19:53:45,557 INFO Included extra file "/etc/supervisor/conf.d/ldap.conf" during parsing
2025-03-08 19:53:45,557 INFO Included extra file "/etc/supervisor/conf.d/pvacms.conf" during parsing
2025-03-08 19:53:45,557 INFO Included extra file "/etc/supervisor/conf.d/sssd.conf" during parsing
2025-03-08 19:53:45,559 INFO supervisord started with pid 1
2025-03-08 19:53:46,568 INFO spawned: 'ldap' with pid 7
2025-03-08 19:53:46,573 INFO spawned: 'pvacms' with pid 8
2025-03-08 19:53:46,574 INFO spawned: 'sssd' with pid 9
2025-03-08 19:53:47,688 INFO success: ldap entered RUNNING state, process has stayed up for > than 1 seconds (startsecs)
2025-03-08 19:53:47,688 INFO success: pvacms entered RUNNING state, process has stayed up for > than 1 seconds (startsecs)
2025-03-08 19:53:47,688 INFO success: sssd entered RUNNING state, process has stayed up for > than 1 seconds (startsecs)

counter_2 Service

  • computer²

  • log in as softioc service account

docker exec -it --user softioc spva_ldap /bin/bash

create a server certificate using the LDAP Authenticator, enter secret when prompted for LDAP password

authnldap -u server

Enter password for softioc@ca130cc9b352:
Keychain file created   : /home/softioc/.config/pva/1.3/server.p12
Certificate identifier  : 47530d89:12147807175996825338

pvxcert -f ~/.config/pva/1.3/server.p12

Certificate Details:
============================================
Certificate ID : 47530d89:12147807175996825338
Entity Subject : CN=softioc, O=epics.org
Issuer Subject : CN=EPICS Root Certificate Authority, C=US, O=certs.epics.org, OU=EPICS Certificate Authority
Valid From     : Sat Mar 08 19:56:17 2025 UTC
Expires On     : Sun Mar 08 19:56:17 2026 UTC
--------------------------------------------

Certificate Status:
============================================
Certificate ID: 47530d89:12147807175996825338
Status        : VALID
Status Issued : Sat Mar 08 19:57:22 2025 UTC
Status Expires: Sat Mar 08 20:27:22 2025 UTC
--------------------------------------------

counter_3 Client

  • computer³

  • log in as a Secure PVAccess client

docker exec -it --user client spva_ldap /bin/bash

  • create a client certificate using the LDAP Authenticator, enter secret when prompted for LDAP password

authnldap

Enter password for client@epics.org:
Keychain file created   : /home/client/.config/pva/1.3/client.p12
Certificate identifier  : 47530d89:11547935522995899879

pvxcert -f ~/.config/pva/1.3/client.p12

Certificate Details:
============================================
Certificate ID : 47530d89:11547935522995899879
Entity Subject : CN=client, O=epics.org
Issuer Subject : CN=EPICS Root Certificate Authority, C=US, O=certs.epics.org, OU=EPICS Certificate Authority
Valid From     : Sat Mar 08 20:00:41 2025 UTC
Expires On     : Sun Mar 08 20:00:41 2026 UTC
--------------------------------------------

Certificate Status:
============================================
Certificate ID: 47530d89:11547935522995899879
Status        : VALID
Status Issued : Sat Mar 08 20:01:59 2025 UTC
Status Expires: Sat Mar 08 20:31:59 2025 UTC
--------------------------------------------

counter_4 Start SoftIOC

  • computer²

  • start SoftIOC

softIocPVX \
    -m user=test,N=tst,P=tst \
    -d ${PROJECT_HOME}/pvxs/test/testioc.db \
    -d ${PROJECT_HOME}/pvxs/test/testiocg.db \
    -d ${PROJECT_HOME}/pvxs/test/image.db \
    -G ${PROJECT_HOME}/pvxs/test/image.json \
    -a ${PROJECT_HOME}/pvxs/test/testioc.acf

INFO: PVXS QSRV2 is loaded, permitted, and ENABLED.
2025-03-08T20:02:23.012770920 WARN pvxs.tcp.init Server unable to bind TCP port 5075, falling back to [::]:40965
2025-03-08T20:02:23.012856587 WARN pvxs.tcp.init Server unable to bind TLS port 5076, falling back to [::]:35255
Starting iocInit
############################################################################
## EPICS R7.0.8.2-DEV
## Rev. R7.0.8.1-123-g48607a42586b1a316cd6
## Rev. Date Git: 2024-11-29 17:08:28 +0000
############################################################################
iocRun: All initialization complete
epics>

counter_5 Get PV value

  • computer³

  • get a PV test:enumExample value from the SoftIOC

pvxinfo -v test:enumExample

Effective config
EPICS_PVA_AUTO_ADDR_LIST=YES
EPICS_PVA_BROADCAST_PORT=5076
EPICS_PVA_CONN_TMO=30
EPICS_PVA_SERVER_PORT=5075
EPICS_PVA_TLS_KEYCHAIN=/home/client/.config/pva/1.3/client.p12
EPICS_PVA_TLS_OPTIONS=on_expiration=fallback-to-tcp on_no_cms=fallback-to-tcp
EPICS_PVA_TLS_PORT=5076
XDG_CONFIG_HOME=/home/client/.config/pva/1.3
XDG_DATA_HOME=/home/client/.local/share/pva/1.3
# TLS x509:47530d89:12147807175996825338:EPICS Root Certificate Authority/softioc@172.17.0.2:35255
test:enumExample from 172.17.0.2:35255
struct "epics:nt/NTEnum:1.0" {
    struct "enum_t" {
        int32_t index
        string[] choices
    } value
    struct "alarm_t" {
        int32_t severity
        int32_t status
        string message
    } alarm
    struct "time_t" {
        int64_t secondsPastEpoch
        int32_t nanoseconds
        int32_t userTag
    } timeStamp
    struct {
        string description
    } display
}

  • verify that connection is TLS

  • TLS x509:47530d89:12147807175996825338:EPICS Root Certificate Authority/softioc @ 172.17.0.2 indicates that:

    • The connection is TLS,

    • The Server end of the channel has been authenticated by the Root Certificate Authority EPICS Root Certificate Authority

    • The Server end of the channel’s name has been authenticated as softioc and is connecting from host 172.17.0.2

checklist Step-By-Step

Env. authnldap

Env. pvacms

Params. authldap

Params. pvacms

Keys and Values

Description
EPICS_AUTH_LDAP
_ACCOUNT_PWD_FILE






{location of password file}
e.g. ~/.config/ldap.pass/
file containing password for the given LDAP user account




-p
--password


{LDAP account password}
e.g. secret
password for the given LDAP user account
EPICS_AUTH_LDAP_HOST

--ldap-host
{hostname of LDAP server}
e.g. ldap.stanford.edu
Trusted hostname of the LDAP server
EPICS_AUTH_LDAP_PORT

--ldap-port
<port_number>
e.g. 389
LDAP server port number. Default is 389

done_all Docker Image

counter_1 Use a Prepackaged spva_std image

  • computer¹

  • open a terminal and load pre-built image

  • don’t forget to add /bin/bash at the end to suppress running the pvacms

docker run -it --name spva_ldap georgeleveln/spva_std:latest /bin/bash

done_all LDAP Service

This section shows how to install and configure a LDAP Service. This is included to enable you to test the LDAP Authenticator before deploying it into your network. It will enable you to configure EPICS agents to log in to the LDAP service using the LDAP Authenticator to authenticate and then generate X.509 certificates.

counter_1 Install prerequisites

  • pre-seed debconf for slapd so that it uses our desired domain and organization

    • domain: epics.org

    • organization: EPICS

export PROJECT_HOME=/opt/epics
export DEBIAN_FRONTEND=noninteractive

echo "slapd slapd/no_configuration boolean false" | debconf-set-selections && \
echo "slapd slapd/domain string epics.org" | debconf-set-selections && \
echo "slapd shared/organization string EPICS" | debconf-set-selections && \
echo "slapd slapd/password1 password secret" | debconf-set-selections && \
echo "slapd slapd/password2 password secret" | debconf-set-selections && \
echo "slapd slapd/backend string MDB" | debconf-set-selections && \
echo "slapd slapd/purge_database boolean true" | debconf-set-selections && \
echo "slapd slapd/move_old_database boolean true" | debconf-set-selections

  • Add LDAP dependencies

    • slapd - LDAP service

    • ldap-utils - LDAP utilities

    • sssd - sssd daemon for centralised identity service access

    • libldap2-dev - development library for compiling pvxs with LDAP Authenticator support

    • libnss and libpam - development libraries that integrate sssd with LDAP

apt-get update && \
apt-get install -y --no-install-recommends \
    slapd \
    ldap-utils \
    sssd \
    libldap2-dev \
    libnss-sss \
    libpam-sss && \
rm -rf /var/lib/apt/lists/*

Hit:1 http://ports.ubuntu.com/ubuntu-ports noble InRelease
Get:2 http://ports.ubuntu.com/ubuntu-ports noble-updates InRelease [126 kB]
Get:3 http://ports.ubuntu.com/ubuntu-ports noble-backports InRelease [126 kB]
Get:4 http://ports.ubuntu.com/ubuntu-ports noble-security InRelease [126 kB]
Get:5 http://ports.ubuntu.com/ubuntu-ports noble-updates/main arm64 Packages [1147 kB]
Get:6 http://ports.ubuntu.com/ubuntu-ports noble-updates/multiverse arm64 Packages [32.7 kB]
Get:7 http://ports.ubuntu.com/ubuntu-ports noble-updates/restricted arm64 Packages [1076 kB]
Get:8 http://ports.ubuntu.com/ubuntu-ports noble-updates/universe arm64 Packages [1305 kB]
Get:9 http://ports.ubuntu.com/ubuntu-ports noble-security/universe arm64 Packages [1028 kB]
...
warn: The home directory `/var/lib/sss' already exists.  Not touching this directory.
warn: Warning: The home directory `/var/lib/sss' does not belong to the user you are currently creating.
invoke-rc.d: could not determine current runlevel
invoke-rc.d: policy-rc.d denied execution of start.
Setting up sssd-proxy (2.9.4-1.1ubuntu6.2) ...
Setting up sssd-ad-common (2.9.4-1.1ubuntu6.2) ...
Setting up sssd-krb5-common (2.9.4-1.1ubuntu6.2) ...
Setting up sssd-krb5 (2.9.4-1.1ubuntu6.2) ...
Setting up sssd-ldap (2.9.4-1.1ubuntu6.2) ...
Setting up sssd-ad (2.9.4-1.1ubuntu6.2) ...
Setting up sssd-ipa (2.9.4-1.1ubuntu6.2) ...
Setting up sssd (2.9.4-1.1ubuntu6.2) ...
Processing triggers for libc-bin (2.39-0ubuntu8.4) ...

counter_2 Rebuild pvxs

  • enable LDAP Authenticator by updating CONFIG_SITE.local

  • do a clean rebuild of pvxs

cd ${PROJECT_HOME}

cat >> CONFIG_SITE.local <<EOF
EVENT2_HAS_OPENSSL = YES
PVXS_ENABLE_PVACMS = YES
PVXS_ENABLE_LDAP_AUTH = YES
EOF

cd pvxs && \
make distclean && \
make -j10 all

make -C ./configure realclean
make[1]: Entering directory '/opt/epics/pvxs/configure'
rm -rf O.*
make[1]: Leaving directory '/opt/epics/pvxs/configure'
make -C ./setup realclean
make[1]: Entering directory '/opt/epics/pvxs/setup'
rm -rf O.*
make[1]: Leaving directory '/opt/epics/pvxs/setup'
make -C ./src realclean
make[1]: Entering directory '/opt/epics/pvxs/src'
rm -rf O.*
make[1]: Leaving directory '/opt/epics/pvxs/src'
make -C ./tools realclean
make[1]: Entering directory '/opt/epics/pvxs/tools'
...
perl -CSD /opt/epics/epics-base/bin/linux-aarch64/makeTestfile.pl linux-aarch64 linux-aarch64 testtls.t testtls
/usr/bin/g++ -o testtlswithcmsandstapling  -L/opt/epics/epics-base/lib/linux-aarch64 -L/opt/epics/pvxs/lib/linux-aarch64 -Wl,-rpath,/opt/epics/epics-base/lib/linux-aarch64 -Wl,-rpath,/opt/epics/pvxs/lib/linux-aarch64     -Wl,--as-needed -Wl,--compress-debug-sections=zlib      -rdynamic         testtlswithcmsandstapling.o certstatusfactory.o certstatusmanager.o certstatus.o    -lpvxs -lCom  -levent_openssl -levent_core -levent_pthreads -lssl -lcrypto
perl -CSD /opt/epics/epics-base/bin/linux-aarch64/makeTestfile.pl linux-aarch64 linux-aarch64 testtlswithcmsandstapling.t testtlswithcmsandstapling
/usr/bin/g++ -o testtlswithcms  -L/opt/epics/epics-base/lib/linux-aarch64 -L/opt/epics/pvxs/lib/linux-aarch64 -Wl,-rpath,/opt/epics/epics-base/lib/linux-aarch64 -Wl,-rpath,/opt/epics/pvxs/lib/linux-aarch64     -Wl,--as-needed -Wl,--compress-debug-sections=zlib      -rdynamic         testtlswithcms.o certstatusfactory.o certstatusmanager.o certstatus.o    -lpvxs -lCom  -levent_openssl -levent_core -levent_pthreads -lssl -lcrypto
perl -CSD /opt/epics/epics-base/bin/linux-aarch64/makeTestfile.pl linux-aarch64 linux-aarch64 testtlswithcms.t testtlswithcms
make[2]: Leaving directory '/opt/epics/pvxs/test/O.linux-aarch64'
make[1]: Leaving directory '/opt/epics/pvxs/test'

counter_3 Configure LDAP

  • Remove the default LDAP configuration and reconfigure slapd non-interactively

rm -rf /etc/ldap/slapd.d && \
dpkg-reconfigure -f noninteractive slapd

invoke-rc.d: could not determine current runlevel
invoke-rc.d: policy-rc.d denied execution of stop.
invoke-rc.d: could not determine current runlevel
invoke-rc.d: policy-rc.d denied execution of stop.
  Moving old database directory to /var/backups:
  - directory unknown... done.
  Creating initial configuration... done.
  Creating LDAP directory... done.
invoke-rc.d: could not determine current runlevel
invoke-rc.d: policy-rc.d denied execution of start.

  • create epics custom schema addition to enable LDAP Authenticator

    • this schema addition will hold the public key for each LDAP user

    • acl protects it so that only the user themselves can write to it but it is readable by anyone

cat > /tmp/epics-schema.ldif <<EOF
dn: cn=epics,cn=schema,cn=config
objectClass: olcSchemaConfig
cn: epics
olcAttributeTypes: ( 1.3.6.1.4.1.99999.1
    NAME 'epicsPublicKey'
    DESC 'Public key EPICS Agents'
    EQUALITY caseExactMatch
    SUBSTR caseExactSubstringsMatch
    SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
    SINGLE-VALUE )
olcObjectClasses: ( 1.3.6.1.4.1.99999.2
    NAME 'epicsAuxiliary'
    DESC 'Auxiliary object class to allow storage of a public key'
    SUP top
    AUXILIARY
    MAY ( epicsPublicKey ) )
EOF

cat > /tmp/epics-acl.ldif <<EOF
dn: olcDatabase={1}mdb,cn=config
changetype: modify
add: olcAccess
olcAccess: {0}to attrs=epicsPublicKey by self write by users read by anonymous read
EOF

/usr/sbin/slapd -h "ldap:/// ldapi:///" -u openldap & \
sleep 5 && \
ldapadd -Y EXTERNAL -H ldapi:/// -f /tmp/epics-schema.ldif && \
ldapmodify -Y EXTERNAL -H ldapi:/// -f /tmp/epics-acl.ldif && \
pkill slapd && \
sleep 2 && \
rm -f /tmp/epics-schema.ldif /tmp/epics-acl.ldif

[1] 2802

[1]+  Done                    /usr/sbin/slapd -h "ldap:/// ldapi:///" -u openldap
SASL/EXTERNAL authentication started
SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth
SASL SSF: 0
adding new entry "cn=epics,cn=schema,cn=config"

SASL/EXTERNAL authentication started
SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth
SASL SSF: 0
modifying entry "olcDatabase={1}mdb,cn=config"

counter_4 Configure LDAP Users

  • create LDAP users

    • base dn: dc=epics, dc=org

    • users: admin, pvacms, softioc, client

    • posix groups: admin, pvacms, softioc, client

    • groups: users, servers, clients, services

    • linux mappings: home directory, shell

    • password: “secret”

cat > /tmp/ldap-data.ldif <<EOF
dn: dc=epics,dc=org
objectClass: dcObject
objectClass: organization
dc: epics
o: EPICS

# Base organizational units
dn: ou=People,dc=epics,dc=org
objectClass: organizationalUnit
ou: People

dn: ou=Groups,dc=epics,dc=org
objectClass: organizationalUnit
ou: Groups

# Create users
dn: uid=admin,dc=epics,dc=org
objectClass: inetOrgPerson
objectClass: posixAccount
objectClass: shadowAccount
objectClass: epicsAuxiliary
cn: admin
sn: admin
uid: admin
uidNumber: 1001
gidNumber: 1001
homeDirectory: /home/admin
loginShell: /bin/bash
userPassword: {SSHA}rDsYFPnFI8zidqcImBer6BGBULvgxjo0
# epicsPublicKey: <base64-encoded public key string>

dn: uid=pvacms,ou=People,dc=epics,dc=org
objectClass: inetOrgPerson
objectClass: posixAccount
objectClass: shadowAccount
objectClass: epicsAuxiliary
cn: pvacms
sn: pvacms
uid: pvacms
uidNumber: 1002
gidNumber: 1002
homeDirectory: /home/pvacms
loginShell: /bin/bash
userPassword: {SSHA}rDsYFPnFI8zidqcImBer6BGBULvgxjo0
# epicsPublicKey: <base64-encoded public key string>

dn: uid=softioc,ou=People,dc=epics,dc=org
objectClass: inetOrgPerson
objectClass: posixAccount
objectClass: shadowAccount
objectClass: epicsAuxiliary
cn: softioc
sn: softioc
uid: softioc
uidNumber: 1003
gidNumber: 1003
homeDirectory: /home/softioc
loginShell: /bin/bash
userPassword: {SSHA}rDsYFPnFI8zidqcImBer6BGBULvgxjo0
# epicsPublicKey: <base64-encoded public key string>

dn: uid=client,ou=People,dc=epics,dc=org
objectClass: inetOrgPerson
objectClass: posixAccount
objectClass: shadowAccount
objectClass: epicsAuxiliary
cn: client
sn: client
uid: client
uidNumber: 1004
gidNumber: 1004
homeDirectory: /home/client
loginShell: /bin/bash
userPassword: {SSHA}rDsYFPnFI8zidqcImBer6BGBULvgxjo0
# epicsPublicKey: <base64-encoded public key string>

# Create groups and add members
dn: cn=admin,ou=Groups,dc=epics,dc=org
objectClass: posixGroup
cn: admin
gidNumber: 1001
memberUid: admin

dn: cn=pvacms,ou=Groups,dc=epics,dc=org
objectClass: posixGroup
cn: pvacms
gidNumber: 1002
memberUid: pvacms

dn: cn=softioc,ou=Groups,dc=epics,dc=org
objectClass: posixGroup
cn: softioc
gidNumber: 1003
memberUid: softioc

dn: cn=client,ou=Groups,dc=epics,dc=org
objectClass: posixGroup
cn: client
gidNumber: 1004
memberUid: client

dn: cn=users,ou=Groups,dc=epics,dc=org
objectClass: groupOfUniqueNames
cn: users
uniqueMember: uid=admin,ou=People,dc=epics,dc=org
uniqueMember: uid=client,ou=People,dc=epics,dc=org

dn: cn=servers,ou=Groups,dc=epics,dc=org
objectClass: groupOfUniqueNames
cn: servers
uniqueMember: uid=softioc,ou=People,dc=epics,dc=org
uniqueMember: uid=pvacms,ou=People,dc=epics,dc=org

dn: cn=clients,ou=Groups,dc=epics,dc=org
objectClass: groupOfUniqueNames
cn: clients
uniqueMember: uid=softioc,ou=People,dc=epics,dc=org
uniqueMember: uid=client,ou=People,dc=epics,dc=org

dn: cn=services,ou=Groups,dc=epics,dc=org
objectClass: groupOfUniqueNames
cn: services
uniqueMember: uid=pvacms,ou=People,dc=epics,dc=org
EOF

  • remove any existing LDAP database contents

  • load the LDAP entries using slapadd

  • fix ownership

  • clean up

rm -rf /var/lib/ldap/* && \
slapadd -l /tmp/ldap-data.ldif && \
chown -R openldap:openldap /var/lib/ldap && \
rm -f /tmp/ldap-data.ldif

Closing DB...

counter_5 Configure SSSD (optional)

  • sssd configuration

    • LDAP set as identity provider

cat > /etc/sssd/sssd.conf <<EOF
[sssd]
services = nss, pam
domains = epics
config_file_version = 2

[domain/epics]
id_provider = ldap
auth_provider = ldap
ldap_uri = ldap://localhost
ldap_search_base = dc=epics,dc=org
# leave these unset for anonymous access.
ldap_default_bind_dn =
ldap_default_authtok =

# Cache credentials so that user information is available even if LDAP temporarily becomes unavailable.
cache_credentials = True

# If a user entry does not specify a home directory, use this pattern.
fallback_homedir = /home/%u

# Use the RFC2307 schema for standard POSIX attributes.
ldap_schema = rfc2307

# enable enumeration (listing all users) for testing.
enumerate = True

debug_level = 0
EOF

  • secure the SSSD configuration

chmod 600 /etc/sssd/sssd.conf && \
chown root:root /etc/sssd/sssd.conf

  • update /etc/nsswitch.conf to use SSSD for passwd, group, and shadow

sed -i 's/^passwd:.*/passwd:        files sss/' /etc/nsswitch.conf && \
sed -i 's/^group:.*/group:          files sss/' /etc/nsswitch.conf && \
sed -i 's/^shadow:.*/shadow:        files sss/' /etc/nsswitch.conf

counter_6 Configure Supervisor to run LDAP and SSSD

  • configure LDAP supervisord

cat > /etc/supervisor/conf.d/ldap.conf <<EOF
[program:ldap]
command=/usr/sbin/slapd -h "ldap:///" -d 1
autostart=true
autorestart=true
stdout_logfile=/var/log/supervisor/ldap.out.log
stderr_logfile=/var/log/supervisor/ldap.err.log
EOF

  • configure SSSD supervisord

cat > /etc/supervisor/conf.d/sssd.conf <<EOF
[program:sssd]
command=/usr/sbin/sssd -i
autostart=true
autorestart=true
stdout_logfile=/var/log/supervisor/sssd.out.log
stderr_logfile=/var/log/supervisor/sssd.err.log
EOF

counter_7 Start Services

  • start LDAP, sssd, and pvacms with LDAP Authenticator support

/usr/bin/supervisord -c /etc/supervisor/supervisord.conf

2025-03-10 12:42:04,390 INFO Included extra file "/etc/supervisor/conf.d/ldap.conf" during parsing
2025-03-10 12:42:04,390 INFO Included extra file "/etc/supervisor/conf.d/pvacms.conf" during parsing
2025-03-10 12:42:04,390 INFO Included extra file "/etc/supervisor/conf.d/sssd.conf" during parsing
2025-03-10 12:42:04,390 INFO Set uid to user 0 succeeded
2025-03-10 12:42:04,391 INFO supervisord started with pid 2830
2025-03-10 12:42:05,403 INFO spawned: 'ldap' with pid 2831
2025-03-10 12:42:05,412 INFO spawned: 'pvacms' with pid 2832
2025-03-10 12:42:05,413 INFO spawned: 'sssd' with pid 2833
2025-03-10 12:42:06,717 INFO success: ldap entered RUNNING state, process has stayed up for > than 1 seconds (startsecs)
2025-03-10 12:42:06,717 INFO success: pvacms entered RUNNING state, process has stayed up for > than 1 seconds (startsecs)
2025-03-10 12:42:06,717 INFO success: sssd entered RUNNING state, process has stayed up for > than 1 seconds (startsecs)

done_all Run SoftIOC

counter_1 Login as softioc in a new shell

  • computer²

docker exec -it --user softioc spva_ldap /bin/bash

counter_2 Verify LDAP config

  • read out entry for softioc from LDAP directory

ldapsearch -x -LLL -b "ou=People,dc=epics,dc=org" "(uid=softioc)"

dn: uid=softioc,ou=People,dc=epics,dc=org
objectClass: inetOrgPerson
objectClass: posixAccount
objectClass: shadowAccount
objectClass: epicsAuxiliary
cn: softioc
sn: softioc
uid: softioc
uidNumber: 1003
gidNumber: 1003
homeDirectory: /home/softioc
loginShell: /bin/bash

ldapsearch -x -LLL -b "ou=People,dc=epics,dc=org" "(uid=softioc)"

dn: uid=softioc,ou=People,dc=epics,dc=org
objectClass: inetOrgPerson
objectClass: posixAccount
objectClass: shadowAccount
objectClass: epicsAuxiliary
cn: softioc
sn: softioc
uid: softioc
uidNumber: 1003
gidNumber: 1003
homeDirectory: /home/softioc
loginShell: /bin/bash

counter_3 Get Certificate

  • create a softioc server certificate. Enter “secret” when prompted for password

    • creates softioc server certificate

    • at location specified by EPICS_PVAS_TLS_KEYCHAIN or ${XDG_CONFIG_HOME}/pva/1.3/server.p12 by default

authnldap -u server

Enter password for softioc@c6e116778b71:
Keychain file created   : /home/softioc/.config/pva/1.3/server.p12
Certificate identifier  : b271f07a:13935791733272200197

counter_4 Check the certificate status is VALID

  • check that the generated certificate is VALID

  • note that the name is softioc - verified against LDAP

  • note that the organization is epics.org - picked up from LDAP

  • note that the expiration date is one day in the future, picked up from default LDAP Authenticator config

  • note that the start date is set to the date of certificate issuance

pvxcert -f ~/.config/pva/1.3/server.p12

Certificate Details:
============================================
Certificate ID : b271f07a:13935791733272200197
Entity Subject : CN=softioc, O=epics.org
Issuer Subject : CN=EPICS Root Certificate Authority, C=US, O=certs.epics.org, OU=EPICS Certificate Authority
Valid From     : Mon Mar 10 12:48:26 2025 UTC
Expires On     : Tue Mar 10 12:48:26 2026 UTC
--------------------------------------------

Certificate Status:
============================================
Certificate ID: b271f07a:13935791733272200197
Status        : VALID
Status Issued : Mon Mar 10 12:49:37 2025 UTC
Status Expires: Mon Mar 10 13:19:37 2025 UTC
--------------------------------------------

counter_5 Run Secure PVAccess Service

  • start the service

softIocPVX \
    -m user=test,N=tst,P=tst \
    -d ${PROJECT_HOME}/pvxs/test/testioc.db \
    -d ${PROJECT_HOME}/pvxs/test/testiocg.db \
    -d ${PROJECT_HOME}/pvxs/test/image.db \
    -G ${PROJECT_HOME}/pvxs/test/image.json \
    -a ${PROJECT_HOME}/pvxs/test/testioc.acf

INFO: PVXS QSRV2 is loaded, permitted, and ENABLED.
2025-03-10T12:51:26.189013708 WARN pvxs.tcp.init Server unable to bind TCP port 5075, falling back to [::]:38601
2025-03-10T12:51:26.189087208 WARN pvxs.tcp.init Server unable to bind TLS port 5076, falling back to [::]:37623
Starting iocInit
############################################################################
## EPICS R7.0.8.2-DEV
## Rev. R7.0.8.1-123-g48607a42586b1a316cd6
## Rev. Date Git: 2024-11-29 17:08:28 +0000
############################################################################
iocRun: All initialization complete
epics>

done_all SPVA Client

counter_1 Login as client in a new shell

  • computer³

docker exec -it --user client spva_ldap /bin/bash

counter_2 Verify LDAP config

  • read out entry for client from LDAP directory

ldapsearch -x -LLL -b "ou=People,dc=epics,dc=org" "(uid=client)"

dn: uid=client,ou=People,dc=epics,dc=org
objectClass: inetOrgPerson
objectClass: posixAccount
objectClass: shadowAccount
objectClass: epicsAuxiliary
cn: client
sn: client
uid: client
uidNumber: 1004
gidNumber: 1004
homeDirectory: /home/client
loginShell: /bin/bash

ldapsearch -x -LLL -b "ou=People,dc=epics,dc=org" "(uid=client)"

dn: cn=client,ou=Groups,dc=epics,dc=org
objectClass: posixGroup
cn: client
gidNumber: 1004
memberUid: client

counter_3 Get Certificate

  • create a client certificate. Enter “secret” when prompted for a password

    • creates a client certificate

    • at location specified by EPICS_PVA_TLS_KEYCHAIN or ${XDG_CONFIG_HOME}/pva/1.3/client.p12 by default

authnldap

Enter password for client@epics.org:
Keychain file created   : /home/client/.config/pva/1.3/client.p12
Certificate identifier  : b271f07a:4841285184560088877

counter_4 Check the certificate status is VALID

  • check that the generated certificate is VALID

  • note that the name is client - verified against LDAP

  • note that the organization is epics.org - picked up from LDAP

  • note that the expiration date is one day in the future, picked up from default LDAP Authenticator config

  • note that the start date is set to the date of certificate issuance

pvxcert -f ~/.config/pva/1.3/client.p12

Certificate Details:
============================================
Certificate ID : b271f07a:1204731550645534180
Entity Subject : CN=client, O=EPICS.ORG
Issuer Subject : CN=EPICS Root Certificate Authority, C=US, O=certs.epics.org, OU=EPICS Certificate Authority
Valid From     : Mon Mar 10 03:32:57 2025 UTC
Expires On     : Tue Mar 11 03:30:32 2025 UTC
--------------------------------------------

Certificate Status:
============================================
Certificate ID: b271f07a:1204731550645534180
Status        : VALID
Status Issued : Mon Mar 10 03:33:58 2025 UTC
Status Expires: Mon Mar 10 04:03:58 2025 UTC
--------------------------------------------

counter_5 Test TLS client operations

pvxget -F tree test:structExample

test:structExample
...

  • show that TLS is being used

pvxinfo -v test:enumExample

Effective config
EPICS_PVA_AUTO_ADDR_LIST=YES
EPICS_PVA_BROADCAST_PORT=5076
EPICS_PVA_CONN_TMO=30
EPICS_PVA_SERVER_PORT=5075
EPICS_PVA_TLS_KEYCHAIN=/home/client/.config/pva/1.3/client.p12
EPICS_PVA_TLS_OPTIONS=on_expiration=fallback-to-tcp on_no_cms=fallback-to-tcp
EPICS_PVA_TLS_PORT=5076
XDG_CONFIG_HOME=/home/client/.config/pva/1.3
XDG_DATA_HOME=/home/client/.local/share/pva/1.3
# TLS x509:b271f07a:13935791733272200197:EPICS Root Certificate Authority/softioc@172.17.0.2:37623
test:enumExample from 172.17.0.2:37623
struct "epics:nt/NTEnum:1.0" {
    struct "enum_t" {
        int32_t index
        string[] choices
    } value
    struct "alarm_t" {
        int32_t severity
        int32_t status
        string message
    } alarm
    struct "time_t" {
        int64_t secondsPastEpoch
        int32_t nanoseconds
        int32_t userTag
    } timeStamp
    struct {
        string description
    } display
}

Note

  • TLS x509:b271f07a:13935791733272200197:EPICS Root Certificate Authority/softioc @ 172.17.0.2 indicates that:

    • The connection is TLS,

    • The Server end of the channel has been authenticated by the Root Certificate Authority EPICS Root Certificate Authority

    • The Server end of the channel’s name has been authenticated as softioc and is connecting from host 172.17.0.2