oitc/acs.relay-control-service

By oitc

•Updated 3 months ago

OITC Access Control System: service that controls the door relays.

Image

Security

Message queues

320

Overview Tags

oitc/acs.relay-control-service repository overview

⁠OITC Access Control System: Relay control service

⁠Quick reference

Maintained by: Michael Oberdorf IT-Consulting⁠

Source code: GitHub⁠

Container image: DockerHub⁠

Access Control System documentation: ACS Documentation⁠

⁠Supported tags and respective `Dockerfile` links

latest, 1.0.0⁠

⁠Description

This service is part of the Michael Oberdorf IT-Consulting (OITC) Access Control System (ACS).

On accessing entry points, this information is available in the internal bus system. This service listens on these events and triggers the relay to unlock the associated door.

This service is NO standalone service. It requires an OITC ACS system to be running.

⁠Configuration

⁠Container configuration

The container get's the configuration from environment variables.

Variable name	Description	Required	Default value
`MQTT_SERVER`	The MQTT server hostname or IP address.	OPTIONAL	`localhost`
`MQTT_PORT`	The TCP port of the MQTT server.	OPTIONAL	`1883`
`MQTT_TLS`	Should SSL communication be enabled (`true`) or not (`false`).	OPTIONAL	`false`
`MQTT_CACERT_FILE`	If TLS is enabled, the path to the CA certificate file to validate the MQTT server certificate.	OPTIONAL	`/etc/ssl/certs/ca-certificates.crt`
`MQTT_TLS_INSECURE`	If TLS is enabled, skip the hostname validation of the TLS certificate.	OPTIONAL	`false`
`MQTT_CLIENT_ID`	The MQTT client id to use for the MQTT connection.	OPTIONAL
`MQTT_USERNAME`	The MQTT username for MQTT authentication.	OPTIONAL
`MQTT_PASSWORD`	The MQTT password for MQTT authentication.	OPTIONAL
`MQTT_PASSWORD_FILE`	The filepath where the MQTT password is stored for MQTT authentication.	OPTIONAL
`MQTT_TOPIC_DOOR_ACCESS`	The MQTT topic to subscribe that contains the door access information.	MANDATORY
`LDAP_SERVER`	The LDAP server that has the relay configuration.	OPTIONAL	`localhost`
`LDAP_PORT`	The LDAP server TCP port.	OPIONAL	`389`
`LDAP_TLS`	Should SSL communication be enabled (`true`) or not (`false`).	OPTIONAL	`false`
`LDAP_USERDN`	The LDAP user DN for LDAP authentication.	OPTIONAL
`LDAP_PASSWORD`	The LDAP password for LDAP authentication.	OPTIONAL
`LDAP_PASSWORD_FILE`	The filepath where the LDAP password is stored for LDAP authentication.	OPTIONAL
`LDAP_BASEDN`	The search base DN where the relay configuration can be found.	MANDATORY
`LDAP_FILTER`	The LDAP filter to search for the relay configuration.	OPTIONAL	`(&(objectclass=ipHost)(objectclass=oitcACSAccessPointExtension)(ipHostNumber={entrypoint_ip}))`
`PROMETHEUS_LISTENER_ADDR`	The listener address to expose the prometheus exporter.	OPTIONAL	`0.0.0.0`
`PROMETHEUS_LISTENER_PORT`	The TCP listener port to expose the prometheus exporter.	OPTIONAL	`8080`
`TZ`	Timezone	OPTIONAL	`UTC`

HINT:

MQTT_PASSWORD_FILE will be priorized before MQTT_PASSWORD
LDAP_PASSWORD_FILE will be priorized before LDAP_PASSWORD

⁠Docker compose configuration

services:
  smtp-bridge-service:
    restart: always
    user: 2200:2200
    image: oitc/acs.relay-control-service:latest
    environment:
      MQTT_SERVER: test.mosquitto.org
      MQTT_PORT: 1883
      MQTT_PROTOCOL_VERSION: 3
      MQTT_TOPIC_ACS_STATUS: location/oitc-acs/general/status
      MQTT_TOPIC_DOOR_ACCESS: location/oitc-acs/entrypoints/+/access
      LDAP_BASEDN: uid=ACS Relay Control Service,ou=Technical Accounts,dc=example,dc=org

A bigger example can be found here: docker-compose.yaml⁠

⁠MQTT message formats

Please have a look to the main documentation: MQTT message reference⁠

⁠Local Relay Board integration

This tool currently support only the MCP2200 chip based USB Relay Board USB Relay Module 4 Channels, for Home Automation - v2⁠ from Denkovi Assembly Electronics LTD⁠.

Further relay type implementations are under development.

To run the container service in a secure way you:

need to allow writes in the container to allow a write to the udev device (read_only: false)
The udev system needs to be configured for the relay to allow writes from non root. See the udev rule example: 53-mcp2200.rules⁠
When using Linux Kernel 6.8, you need to disable the kernel module hid_mcp2200. See the modprobe blacklist example: blacklist_mcp2200.conf⁠

⁠Donate

I would appreciate a small donation to support the further development of my open source projects.

⁠License

Apache License Version 2.0⁠

Tag summary

Recent tags

Content type

Image

Digest

sha256:ed4251fd8…

Size

94.2 MB

Last updated

3 months ago

docker pull oitc/acs.relay-control-service