github.com/simpleiot/simpleiot@v0.18.3/docs/user/configuration.md (about)

     1  # Configuration
     2  
     3  ## Environment variables
     4  
     5  Environment variables are used to control various aspects of the application.
     6  The following are currently defined:
     7  
     8  - **General**
     9    - `SIOT_HTTP_PORT`: http network port the SIOT server attaches to (default
    10      is 8118)
    11    - `SIOT_DATA`: directory where any data is stored
    12    - `SIOT_AUTH_TOKEN`: auth token used for NATS and HTTP device API, default is
    13      blank (no auth)
    14    - `OS_VERSION_FIELD`: the field in `/etc/os-release` used to extract the OS
    15      version information. Default is `VERSION`, which is common in most distros.
    16      The Yoe Distribution populates `VERSION_ID` with the update version, which
    17      is probably more appropriate for embedded systems built with Yoe. See
    18      [ref/version](../ref/version.md).
    19  - **NATS configuration**
    20    - `SIOT_NATS_PORT`: Port to run NATS on (default is 4222 if not set)
    21    - `SIOT_NATS_HTTP_PORT`: Port to run NATS monitoring interface (default
    22      is 8222)
    23    - `SIOT_NATS_SERVER`: defaults to nats://127.0.0.1:4222
    24    - `SIOT_NATS_TLS_CERT`: points to TLS certificate file. If not set, TLS is not
    25      used.
    26    - `SIOT_NATS_TLS_KEY`: points to TLS certificate key
    27    - `SIOT_NATS_TLS_TIMEOUT`: Configure the TLS upgrade timeout. NATS defaults to
    28      a 0.5s timeout for TLS upgrade, but that is too short for some embedded
    29      systems that run on low end CPUs connected over cellular modems (we've see
    30      this process take as long as 4s). See NATS
    31      [documentation](https://docs.nats.io/nats-server/configuration/securing_nats/tls#tls-timeout)
    32      for more information.
    33    - `SIOT_NATS_WS_PORT`: Port to run NATS websocket (default is 9222, set to 0
    34      to disable)
    35  - **Particle.io**
    36    - `SIOT_PARTICLE_API_KEY`: key used to fetch data from Particle.io devices
    37      running [Simple IoT firmware](https://github.com/simpleiot/firmware)
    38  
    39  ## Configuration export
    40  
    41  Nodes can be exported to a YAML file. This is a useful to:
    42  
    43  - backup the current configuration
    44  - dump node data for debugging
    45  - transfer a configuration or part of a configuration from one instance to
    46    another
    47  
    48  To export the entire tree:
    49  
    50  `siot export > backup.yaml`
    51  
    52  A subset of the tree can be exported by specifying the node ID:
    53  
    54  `siot export -nodeID 9d7c1c03-0908-4f8b-86d7-8e79184d441d > export.yaml`
    55  
    56  ## Configuration import
    57  
    58  Nodes defined in a YAML file can be imported into a running SIOT instance using
    59  the CLI, or the Go API. When using the CLI, the import file must be specified on
    60  STDIN. If there are any node IDs in the import they are mapped to new IDs to
    61  eliminate any possibility of ID conflicts if the config is imported into
    62  multiple systems with a common upstream sync, etc.
    63  
    64  If nodes reference each other (for instance a rule condition and a Modbus node),
    65  then friendly IDs can be used to make it easy to edit and reference. These
    66  friendly IDs will be replaced by a common UUID during import.
    67  
    68  To import nodes at a specific location (typically a group), then you can specify
    69  the parent node ID. This ID can be obtained by expanding the node and clicking
    70  the copy button. This will put the ID into your system copy buffer.
    71  
    72  `siot import -parentID 9d7c1c03-0908-4f8b-86d7-8e79184d441d < import.yaml`
    73  
    74  If you want to wipe out any existing state and restore a SIOT to a known state,
    75  you can run an import with the `-parentID` set to `root`. It is highly
    76  recommended you restart SIOT after this is done to minimize the chance of any
    77  code still running that caches the root ID which has now changed.
    78  
    79  `siot import -parentID root < backup.yaml`
    80  
    81  Again, by default, the import command will create new IDs to minimize the chance
    82  of any ID conflicts. If you want to preserve the IDs in the YAML file, you can
    83  specify the `-preserveIDs` option -- **WARNING**, use this option with caution.
    84  Importing a backup to `root` with `-preserveIDs` is a handy way to restore a
    85  system to a known previous state. However, new nodes that don't exist in the
    86  backup will not be deleted -- the import only adds nodes/points.
    87  
    88  If authentication or a different server is required, this can be specified
    89  through command line arguments or the following environment variables (see
    90  descriptions above):
    91  
    92  - `SIOT_NATS_SERVER`
    93  - `SIOT_AUTH_TOKEN`
    94  
    95  **It is easy to make a mess with the import command, so think through what you
    96  are doing first. SIOT does not prevent you from making a mess!**
    97  
    98  `siot import --help` for more details.
    99  
   100  Example YAML file:
   101  
   102  ```yaml
   103  nodes:
   104    - type: group
   105      points:
   106        - type: description
   107          text: "group 1"
   108      children:
   109        - type: variable
   110          points:
   111            - type: description
   112              text: var 1
   113            - type: value
   114              value: 10
   115  ```