TBD
1 - Backend Configuration
MyController backend configurations are loaded at the time of startup.
Configurations should be in the YAML file format.
Samples are available in the source code repository
Note
mycontroller.yaml
file will not be included in the backup for the security reasons.
mycontroller.yaml
secret: 5a2f6ff25b0025aeae12ae096363b51a # (1)
web: # (2)
web_directory: /ui
enable_profiling: false
http:
enabled: true
bind_address: "0.0.0.0"
port: 8080
https_ssl:
enabled: false
bind_address: "0.0.0.0"
port: 8443
cert_dir: /mc_home/certs/https_ssl
https_acme:
enabled: false
bind_address: "0.0.0.0"
port: 9443
cache_dir: /mc_home/certs/https_acme
acme_directory:
email: hello@example.com
domains: ["mycontroller.example.com"]
logger: # (3)
mode: development
encoding: console
level:
core: info
web_handler: info
storage: info
metrics: warn
directories: # (4)
data: /mc_home/data
logs: /mc_home/logs
tmp: /mc_home/tmp
secure_share: /mc_home/secure_share
insecure_share: /mc_home/insecure_share
bus: # (5)
type: natsio
topic_prefix: mc_production
server_url: nats://192.168.1.21:4222
tls_insecure_skip_verify: false
connection_timeout: 10s
gateway: # (6)
ids: []
labels:
location: core
database: # (7)
storage: memory_db
metrics: influxdb_v1_8
databases: # (8)
- name: memory_db
type: memory
dump_enabled: true
dump_interval: 10m
dump_dir: "memory_db"
dump_format: ["yaml", "json"]
load_format: "yaml"
- name: influxdb_v1_8
type: influxdb_v2
uri: http://192.168.1.21:8086
token:
username:
password:
organization:
bucket: mycontroller
batch_size:
flush_interval: 5s
secret
is used to encrypt the password, token and other sensitive details in gateways, handlers, etc., and keep encrypted data in the storage database.
At later point if you change thesecret
you have update manually the existing passwords and tokens if any
Uses AES-256 encryption then base64 encodingweb
holds the web configurationslogger
- controls the logs level of a different components.directories
- points to custom locations.bus
- message bus configurations, will be used for internal communications.gateway
- filters to load gateways to this instance.database
- says which configuration should be used forstorage
andmetrics
. Name of the configuration should be supplied. It looks the detailed configuration fromdatabases
list.databases
- keeps the detailed configurations of a different databases.
Web Configuration
web:
web_directory: /ui # (1)
documentation_url: http://192.168.1.21:8079/docs/ # (2)
enable_profiling: false # (3)
http: # (4)
enabled: true
bind_address: "0.0.0.0"
port: 8080
https_ssl: # (5)
enabled: false
bind_address: "0.0.0.0"
port: 8443
cert_dir: /mc_home/certs/https_ssl
https_acme: # (6)
enabled: false
bind_address: "0.0.0.0"
port: 9443
cache_dir: /mc_home/certs/https_acme
acme_directory:
email: hello@example.com
domains: ["mycontroller.example.com"]
web_directory
- production build of Web Consoledocumentation_url
- if you are in a private environment and want to keep the document server locally. Add your documentation server url.
In MyController server default documentation url will be replaced with this url.enable_profiling
- enables GoLang profiling on the http handler at/debug/pprof/
http
- HTTP handlerhttps_ssl
- HTTPS SSL handlerhttps_acme
- HTTPS ACME handler
HTTP handler
HTTP handler serves the web console
and api
as un-encrypted.
This setup can be used in a trusted network.
http:
enabled: true # (1)
bind_address: "0.0.0.0" # (2)
port: 8080 # (3)
enabled
- can enable or disable the http handler. if no values supplied, will be treated as disabledbind_address
- IP address to bind,0.0.0.0
- binds to all the available network interfaces.port
- listening port number
HTTPS SSL handler
HTTPS SSL handler serves the web console
and api
as encrypted.
You can use self signed certificate or CA signed certificate.
You can use this handler to access the web console on the untrusted networks
https_ssl:
enabled: false # (1)
bind_address: "0.0.0.0" # (2)
port: 8443 # (3)
cert_dir: /mc_home/certs/https_ssl # (4)
enabled
- can enable or disable the https ssl handler. if no values supplied, will be treated as disabledbind_address
- IP address to bind,0.0.0.0
- binds to all the available network interfaces.port
- listening port numbercert_dir
- certificate and key files location.
https_ssl
operates in two modes.
Generate the certificates automatically
If there is no custom.crt
and custom.key
found on the cert_dir
location MyController generates a crt and key files and stores on cert_dir
location. Auto generated file names will as mc_generated.crt
and mc_generated.key
.
Auto generated certificate details:
- RSA Bits - 2048
- Organization name - MyController.org
- Validity - 365 days
If you want to change these details, you have to generate a certificate manually as mentioned in Custom certificate
Custom certificate
If you want to use your custom certificates, you have to place your files on the cert_dir
location.
The name of the files must be as custom.crt
and custom.key
To generate self signed certificate there are multiple options available. Here is a quick sample,
openssl genrsa -out custom.key 2048
openssl req -new -x509 -sha256 -key custom.key -out custom.crt -days 365
Important
Ifcustom.crt
and custom.key
files are present in the cert_dir
, it get the higher precedence than the auto generated files.
HTTPS ACME handler
Automated Certificate Management Environment (ACME) is a standard protocol for automating domain validation, installation, and management of X.509 certificates.
Letsencrypt is popular free certificate provider.
This handler can take care of the life cycle of the certificate. That is to get the certificate first time and subsequence renewals.
- The default ACME directory url will be pointing to letsencrypt, https://acme-v02.api.letsencrypt.org/directory
- The certificates will be renewed 30 days prior to expiration
- ACME challenge will be verified using
tls-alpn-01
. Extra port is not required. To know more abouttls-alpn-01
visit Letsencrypt guide - You have to configure port forward to the
https_acme
port. This port should be reachable on public ip of443
port. acme challenge will be verified only on443
port.
https_acme:
enabled: false # (1)
bind_address: "0.0.0.0" # (2)
port: 9443 # (3)
cache_dir: /mc_home/certs/https_acme # (4)
acme_directory: # (5)
email: hello@example.com # (6)
domains: ["mycontroller.example.com"] # (7)
enabled
- can enable or disable the https acme handler. if no values supplied, will be treated as disabledbind_address
- IP address to bind,0.0.0.0
- binds to all the available network interfaces.port
- listening port numbercache_dir
- certificate and related files received from the provider will be stored on this directory.acme_directory
- ACME provider directory url, if you leave it blank the default will be https://acme-v02.api.letsencrypt.org/directoryemail
- email address used to get the certificate from the providedomains
- You can have single or multiple domains
Logger
logger:
mode: development # (1)
encoding: console # (2)
level: # (3)
core: info
web_handler: info
storage: info
metrics: warn
mode
- supports two modes.development
- prints the detailed information about the log fieldsproduction
- prints the restricted information about the log fields
encoding
- log encoding formatconsole
- suits for console displayjson
- prints logs in json format, suits for processing with external tools
level
- restrict the log level. supported levels:debug
,info
,warn
,error
,fatal
. You can restrict the log level to a specific service.core
- entire system log level. This is applicable for gateway service too.web_handler
- http handlers log levelstorage
service log levelmetrics
service log level
Directories
directories:
data: /mc_home/data # (1)
logs: /mc_home/logs # (2)
tmp: /mc_home/tmp # (3)
secure_share: /mc_home/secure_share # (4)
insecure_share: /mc_home/insecure_share # (5)
MyController uses these directories to keep configurations, logs, and temporary files.
data
- keeps all configurations on this location. in-memory database, firmware, etc.,logs
- keeps gateway logs and system logstmp
- used as a temporary location for MyController servicessecure_share
- you can keep custom files on this location. This location can be accessed via MyController instance url,http://mycontroller-ip:8080/secure_share
. It needs authentication. access token can be supplied via header or on the url.insecure_share
- you can keep custom files on this location. This location can be accessed via MyController instance url,http://mycontroller-ip:8080/insecure_share
. It is open to everyone. Authentication not required
Message Bus
bus:
type: natsio # (1)
topic_prefix: mc_production # (2)
server_url: nats://192.168.1.21:4222 # (12)
tls_insecure_skip_verify: false # (3)
connection_timeout: 10s # (4)
type
- There are two type of message bus available.embedded
- internal message bus. You cannot include external gatewaynatsio
- external message bus
topic_prefix
- A natsio message bus can be used for different applications. Based on this topics we can separate a specific MyController instance.server_url
- natsio server urltls_insecure_skip_verify
- allow or disallow insecure connectionsconnection_timeout
- connection establishment timeout
Important
When you use external gateway service. You should use external message bus service(natsio) Also should use the same message bus configurations in the MyController instance and in the external gateway instances.Gateway
gateway:
ids: [] # (1)
labels: # (2)
location: core
We can restrict to load a specific gateway to this service.
ids
- filtered by list of gateways idlabels
- filtered based on the labels. detailed guide
Note
Empty filter loads all the gateways.Databases
You can define ant number of databases.
However only two configurations used. one for storage
and another one is for metrics
The name
and type
fields are common in across all the database configurations
databases:
- name: memory_db # (1)
type: memory # (2)
dump_enabled: true
dump_interval: 10m
dump_dir: "memory_db"
dump_format: ["yaml", "json"]
load_format: "yaml"
name
of the database, should a be unique nametype
of the database
MyController needs two type of databases.
Storage Databases
MyController supports two type of storage databases
In Memory Database
In memory is a special database designed by MyController.org. It keeps all the configuration data in the memory(RAM). Dumps all the data into the disk on a specified interval. When MyController start up, loads all the data from the disk to memory.
- We can reduce the number of writes to disk on configurations change. This can increase the life time of the disk.
- This is very good choice for a tiny hardwares(ie: Raspberry PI).
- In-Memory database will be faster as the configurations are in memory(RAM).
Important
Assuming dump enabledWhen the MyController server terminated gracefully, dumps all the configuration data onto disk.
So there will be no loss.
However there will be some loss, if the service terminated forcefully.
name: memory_db # (1)
type: memory # (2)
dump_enabled: true # (3)
dump_interval: 10m # (4)
dump_dir: "memory_db" #(5)
dump_format: ["yaml", "json"] # (6)
load_format: "yaml" # (7)
name
of the database, should be unique nametype
should bememory
dump_enabled
- enable or disable sync to disk feature. Copies in memory configurations to diskdump_interval
- how long once the sync should happen.dump_dir
- directory used to dump in memory configurations. default:memory_db
dump_format
- supportsyaml
andjson
formats. You can ask to dump a format or both formatsload_format
- even though you can dump configurations onyaml
and/orjson
format. at the time of startup, only one format can be used. Make sure you are using this format on thedump_format
MongoDB Database
MyController supports MongoDB local or cloud version.
name: mongo_local
type: mongodb
database: mcdb
uri: mongodb://192.168.1.21:27017
name
of the database, should be a unique nametype
should bemongodb
database
- name of the database in your MongoDBuri
of the database. supports cloud database format too.
Metric Databases
MyController supports two type of metric databases
Void Database
If you do not want track metrics in your MyController instance you can go with void database. It means nothing recorded.
name: dummy_metric_database
type: void_db
name
of the database, should be uniquetype
should bevoid_db
InfluxDB
MyController uses InfluxDB to keep the metrics data. It can be local InfluxDB instance or can be in the cloud.
MyController supports InfluxDB 1.8.4 or above versions.
Note
Flux query supports for InfluxDB 1.8.x and InfluxDB 2.x,
however there is an issue on ARM architecture in mean
and query
functions
As a workaround, MyController uses two type of InfluxDB query clients.
name: influxdb_v1.8_local # (1)
type: influxdb_v2 # (2)
uri: http://192.168.1.21:8086 # (3)
token: # (4)
username: # (5)
password: # (6)
organization: # (7)
bucket: mc_db # (8)
query_client_version: # (9)
batch_size: # (10)
flush_interval: 1s # (11)
name
of the database, should be a unique nametype
should beinfluxdb_v2
uri
is the database connection URItoken
- authentication token used in InfluxDB 2.xusername
- authenticate using username and passwordpassword
- authenticate using username and password. Ifusername
specifiedpassword
is a mandatory field.organization
- used in InfluxDB 2.xbucket
- database name used for MyController. In InfluxDB 2.x it is calledbucket
query_client_version
- MyController uses two type of query clients. It is recommended to keep it blank. MyController can choose automatically based the the database version used. However we can override the automatic selection by providing one for the option,v1
- InfluxDB 1.8.xv2
- InfluxDB 2.x
batch_size
- sends the metrics to InfluxDB when meets the batch sizeflush_interval
- sends the metrics to InfluxDB when meets the interval
Sample of Cloud InfluxDB Configuration
name: influxdb_v2_cloud
type: influxdb_v2
uri: https://eu-central-1-1.aws.cloud2.influxdata.com
token: VGhpcyBpcyBmYWtlIHRva2VuLCB0YWtlIHlvdXIgZnJvbSBNb25nb0RCIGNsb3VkCg==
organization: example@example.com
bucket: mc_bkt
batch_size:
flush_interval: 1s
Note
MongoDB Cloud offers free services for small applications.2 - Gateway Configuration
MyController gateway configurations are loaded at the time of startup.
Configurations should be in the YAML file format.
gateway.yaml
Refer backend configuration detailed guide to know about the configurations
logger:
mode: development
encoding: console
level:
core: info
storage: info
metrics: warn
directories:
data: /mc_home/data
logs: /mc_home/logs
tmp: /mc_home/tmp
bus:
type: natsio
topic_prefix: mc_production
server_url: nats://192.168.1.21:4222
tls_insecure_skip_verify: false
connection_timeout: 10s
gateway:
ids: []
labels:
location: external_gw1