Skip to content

C1 Module Proxy


C1 Core requires a constant TCP connection for bidirectional communication. This is hard to do using standard webservers like Nginx or Apache. C1 Module Proxy is a small service taking over exactly this task. It connects to C1 Core and handles all communication with it.


Using Docker

C1 Module Proxy provides a Docker template image with Ubuntu Focal and C1 Module Proxy preinstalled. You can pull this image with:

docker pull

Within the image you just need to modify the settings and files in /etc/c1-module-proxy/ (or mount them).


Here's a template you can use to deploy c1-module-proxy in Kubernetes. A secret with the C1 Core client certificates must exist in the namespace in c1-core-client-tls:

apiVersion: v1
kind: Service
    app: c1-module-proxy
  name: c1-module-proxy
  namespace: <your namespace>
  clusterIP: None
    - port: 80
    app: c1-module-proxy
apiVersion: apps/v1
kind: StatefulSet
  name: c1-module-proxy
  namespace: <your namespace>
  replicas: 1
  minReadySeconds: 60
      app: c1-module-proxy
      maxSurge: 0
      maxUnavailable: 1
    type: RollingUpdate
        app: c1-module-proxy
        network-policy: permit-local-traffic
      - name: c1-module-proxy
        - containerPort: 80
          protocol: TCP
          failureThreshold: 3
          initialDelaySeconds: 60
          periodSeconds: 30
          successThreshold: 1
            port: 80
          timeoutSeconds: 1
          failureThreshold: 3
          initialDelaySeconds: 5
          periodSeconds: 30
          successThreshold: 1
            port: 80
          timeoutSeconds: 1
        imagePullPolicy: Always
        - name: c1-module-proxy-config
          mountPath: /etc/c1-module-proxy/main.conf
          subPath: main.conf
          readOnly: true
        - name: c1-core-client-tls
          mountPath: /etc/c1-module-proxy/c1-core-client-tls
          readOnly: true
      - name: gitit-de
      - name: c1-module-proxy-config
          defaultMode: 288
          optional: false
          name: c1-module-proxy-config
      - name: c1-core-client-tls
          defaultMode: 292
          optional: false
          secretName: c1-core-client-tls
apiVersion: v1
kind: ConfigMap
  main.conf: <base64-encoded main.conf>
  name: c1-module-proxy-config
  namespace: <your namespace>

Install manually


C1 Module Proxy requires

  • libhomegear-base and

  • libc1-module.

In addition

  • GnuTLS and
  • GCrypt

are required.

libhomegear-base can be downloaded as a Debian package for Debian and Ubuntu from libc1-module needs to be compiled manually.

Compilation of libc1-module requires g++, automake and libtool. Under Debian and Ubuntu install the packages automake, libtool and build-essential.

To compile libc1-module, clone the repository and execute:

cd /path/to/libc1-module

GnuTLS and GCrypt can be installed by installing the packages gnutls-dev and libgcrypt-dev.

c1-module-proxy requires cmake for compilation, so this package needs to be installed as well.


To compile C1 Module Proxy, clone the repository and execute:

cd /path/to/c1-module-proxy
mkdir build
cd build
cmake ..
make -j4
strip c1-module-proxy
cp c1-module-proxy /usr/bin
cd ..

Now create the settings and log directory and copy the example configuration:

mkdir /etc/c1-module-proxy
cp misc/* /etc/c1-module-proxy
mkdir /var/log/c1

Create a user, e. g. c1 to run the service as user. Then set permissions on the log directory:

adduser --system --no-create-home --shell /bin/false --group c1
chown c1:c1 /var/log/c1

Configure module

Module configuration is also done in C1 Module Proxy. You can find the required entries in /etc/c1-module-proxy/main.conf in section Module information:

moduleName = {"de-DE": "Mein Modul", "en-US": "My module"}
moduleDescription = {"de-DE": "", "en-US": ""}
moduleUiMenu = {"label":{"de-DE":"Mein Modul","en-US":"My module"},"icon":"fontawesome/fa-heartbeat","url":""}
moduleUiCategory =
moduleAppUiUrl =
moduleAppUiCategory =
moduleAclInfo = {"version":1,"rpcMethods":{"method1":"read","method2":"write"}}
moduleEventSubscriptions = ["c1-core/bp/+/au/+/association"]

moduleName and moduleDescription are self-explaining.

moduleUiMenu is only required for modules providing an user interface for C1 Core. This creates a menu entry in C1 Core with the provided information.

moduleUiCategory specifies under which category or heading the menu entry is sorted in.

moduleAppUiUrl is only required for modules that provide an user interface for the inhabitant smartphone app. The specified page is opened when the module is selected in the app.

moduleAppUiCategory specifies under which category the app entry is placed.

moduleAclInfo is mandatory and contains the list of all RPC methods implemented by the module. Every method must be added to the property rpcMethods and requires one of:

  • read: To execute this method, read permissions are required.
  • write: To execute this method, write permissions are required.
  • event: To execute this method, event permissions are required.
  • admin: To execute this method, administrative permissions are required.

It is not required to specify REST methods here. REST methods are associated to the permissions above by their HTTP method. Only read and write are supported at the moment for REST methods.


When the ACL info is updated after the first registration, a restart of C1 Core is required after the update to the ACL info. The reason is that C1 Core regards this info as static information and caches it in memory.

moduleEventSubscriptions contains all topics the module wants to subscribe to. See Events.

First connection

On first connection the module is registered to Sensaru Cloud. To be able to connect there is one more thing required: A client certificate. The client certificate needs to be requested from one of the certificate administrators. To create the certificate a module ID (e. g. c1-device-management) needs to be defined. This ID is part of the common name of the signed certificate and this ID is used to identify the module within Sensaru Cloud.


The common name is a base64-encoded JSON. The JSON looks like this: {"type":"module","id":"c1-device-management","index":1,"date":1578005399878,"version":1,"environment":"dev"}

Place the certificate and key in the locations specified in /etc/c1-module-proxy/main.conf (parameters coreClientCert and coreClientKey).


Never ever upload these certificates to a code repository and never ever store them within Docker images or containers. To use them within containers, use mounts.

High availability and scalability

Any module is required to be able to run in multiple instances over multiple datacenters. C1 Module Proxy and C1 Core already do a lot of the backend work, so you can start multiple instances of C1 Module Proxy. When multiple module instances are available, C1 Core randomly selects a module instance to direct requests to.


Requests originating from C1 Core

Your application needs to listen on the hostname and port specified in /etc/c1-module-proxy/main.conf (parameters localRpcHost and localRpcPort) and handle JSON-RPC requests on an arbitrary path. The path C1 Module Proxy sends the requests to can be specified in /etc/c1-module-proxy/main.conf (parameter localRpcPath).

Every request coming from C1 Core is forwarded to your application. The response from your application is forwarded back to C1 Core.

Requests originating from your application

When you want to call a RPC method on C1 Core or another module, send this request to the listen address and the listen port specified in /etc/c1-module-proxy/main.conf (parameters httpListenAddress and httpListenPort). The used path is irrelevant.

Calling moduleMethod

In contrast to the description here, when calling moduleMethod the response is returned directly when C1 Module Proxy is used. This makes usage much easier. The underlying call is still asynchronous.

More information

For more information read the section about inter-module communication.


First read the section about module REST API's.

C1 Module Proxy takes the tunneled RPC call and translates it back to a REST call including HTTP headers. The REST request is called on the same hostname and port as specified in localRpcHost and localRpcPort in /etc/c1-module-proxy/main.conf.

The RPC metadata Struct which includes for example the logged in user and principal is passed as a base64-encoded JSON in the header field C1-VERIFIED-METADATA. Like this you can control data access and only return data the user has access to.

An example header might look like this:

C1-VERIFIED-METADATA: eyJpYnNIb21lQ2xpZW50SWQiOiIiLCJpYnNIb21lQ2xpZW50VXNlcnMiOltdLCJzb3VyY2VNb2R1bGVJZCI6Imlicy1jb3JlIiwidXNlcklic0hvbWVDbGllbnRzIjp7ImFjdGl2ZSI6e30sImFsbCI6e319LCJ1c2VySWQiOnsiYnAiOiIiLCJpZCI6IjE1N2Q5MzUwLTFkYjgtMTFlOS04ZTY2LTJmNzFhMGJlNGNjNSIsInNkIjoiIiwic3AiOiI0ODEwOTM1MC0xZGI2LTExZTktOGU2Ni0yZjcxYTBiZTRjYzUiLCJ0eXBlIjoxfX0=

The decoded base64 from above contains the following JSON:

  "homeClientId": "",
  "homeClientUsers": [],
  "sourceModuleId": "c1-core",
  "userHomeClients": {
    "active": {},
    "all": {}
  "userId": {
    "bp": "",
    "id": "157d9350-1db8-11e9-8e66-2f71a0be4cc5",
    "sd": "",
    "sp": "48109350-1db6-11e9-8e66-2f71a0be4cc5",
    "type": 1

See the chapter about verified metadata for more information.


It is mandatory that the logged-in user is only able to access data from it's own principal and data of principals that are hirarchically below the user's principal level (e. g. a system distributor user is allowed to access data from the system distributor's business partners).

Apart from that a user can be granted or denied permission

  1. per RPC method or
  2. per REST method/path combination.


Never ever allow a user access to data outside of it's own principal scope!

Permission types

There are four possible permission types that can be assigned to a RPC method:

  1. read
  2. write
  3. event
  4. isAdmin

For REST currently no permission types can be assigned manually to REST methods or paths. This is on our issue list. Currently permissions are set automatically in C1 Core. See below.

RPC permissions

The per RPC method permission is given by the group ACLs assigned to the user in C1 Core. This permission is checked within C1 Core, so there are no checks required within the module.

For this to work, the module must pass ACL information to C1 Core upon module registration. This ACL information is a JSON defined in main.conf in C1 Module Proxy (setting moduleAclInfo, see above).

REST permissions

REST permission types are assigned automatically based on the HTTP method. The association is as follows:

HTTP method Permission type
DELETE write
GET read
PATCH write
POST write
PUT write

The permission is checked within C1 Core, so there are no checks required within the module.