Skip to content

Latest commit

 

History

History
188 lines (120 loc) · 7.15 KB

InitialSetup.md

File metadata and controls

188 lines (120 loc) · 7.15 KB

Initial setup

Note that this repository is meant as a framework for specific factory and device configurations. Specific device factories are required to:

  1. Create 4 private git repositories of the following kind:

    The my_ prefix should be replaced by whatever you prefer.

    1. my_factory_install: A private git repository where factory specific knownledge will be stored.

      No devices will ever get access to this repository.

    2. my_device_config: A private git repository where the device nixos configuration will be stored.

      All devices will get access to this repository.

      Note that it is possible but not advised for production setups to embbed the device configuration as part of my_factory_install. This is the approach taken for ./demo-nixos-config.

    3. my_factory_secrets: A private git repository containing the secrets that only the factory technicians / developers should have access to.

      The secrets found there can only be accessed by the factory technicians / developers through their respective gnupg identity.

    4. my_device_secrets: A private git repository containing the secrets each individual device should have access to.

      In this repository, one will find one sub store per device. The secrets in each device sub stores can only be accessed by the specific device and its factory devs/techs through their respective gnupg identities.

  2. Create its own specific version of demo-nixos-config.

    In my_device_config.

    This repository should contains the 2 following mandatory folders:

    1. ./device-type:

      Contain a sub directory for each device type the specific factory is able to produce.

      Each of these sub directory should contain the following files:

      • nixos/configuration.nix

        The nixos configuration for a device of this type. It should import at some point the nixos/hardware-configuration.nix file.

      • nixos/hardware-configuration.nix

        The nixos hw configuration as generated by nixos-generate-config on this device.

    2. ./device:

      Contain a sub directory for each specific devices by device id.

      Each of these sub directory will usually contain only a device.json which holds the specific device configuration.

      It is however possible to have a specific nixos configuration for a particular device in which case this sub directory will contain a nixos/configuration.nix file as well.

    3. ./release.nix

      This is the nix function that given a device id (name of the directory under ./device) will generate the nixos configuration for this particular device.

  3. Create its own specific version of ./scripts/factory-install depending on ./scripts/factory-common-install.

    Under my_factory_install/scripts/factory-install.

    These specific tools will be responsible for initializing the following state *.yaml files which are expected for this repos's tools to function properly:

    1. my_factory_install/.factory-info.yaml.
    2. my_device_config/.current-device.yaml

    The specific repository configuration should be specify through environment variables in scripts/factory-install/enter-env.sh.

    2 mandatory env var should be set there:

    1. PKG_NSF_FACTORY_COMMON_INSTALL_DEVICE_TYPE_FACTORY_INSTALL_DEFS_DIR

      Should points to the root of the factory install device type definitions (e.g.: my_factory_install/device-type).

    2. PKG_NSF_FACTORY_COMMON_INSTALL_DEVICE_OS_CONFIG_REPO_DIR

      Should points to the root of your local of my_device_config.

    3. PKG_NSF_FACTORY_COMMON_INSTALL_DEVICE_CONFIG_TYPE_DEFS_DIR

      Should point to the location of the device configuration type defintions dir. (e.g.: my_device_config/device-type).

    4. PKG_NSF_FACTORY_COMMON_INSTALL_DEVICE_CONFIG_SSH_AUTH_DIR

      Should point to a writable location in the device configuration (e.g.: my_factory_install/device-ssh) where the factory tools will be able to create / read and modify a set of files related to the allowed access to devices through ssh.

      This directory will be managed according to nsf-ssh-auth's policy.

      See nsf-ssh-auth - Readme for more details.

      You configuration will then be able to exploit this information to grant access to the public keys listed in the json file.

      TODO: Document how to integrate this with a device configuration.

      TODO: Document special setup to confer special ssh priviledges to factory users listed in the factory-installed-by array (member of the device state file).

      TODO: Document how it is also possible to setup a separate ssh authorization directory in a separate core repository and merging this directory with the factory install one.

      TODO: Document how it is possible to user the authorized-on directory to authorize some users and groups temporarily.

    It is recommended that the following helpers are provided under ./scripts/factory-install/bin:

    • factory-state-init: responsible to initialize the factory's .factory-info.yaml file.

    • device-state-init-new: responsible to initialize a new device's .current-device.yaml file.

    The following helpers can optionally be provided as well:

    • factory-repos-update-dependencies: responsible to clone / synchronize the repository on which my_factory_install.

    • factory-repos-update: responsible to clone / synchronize all the repositories including my_factory_install.

    • factory-repos-init-mr-config: responsible to create a .mrconfig in this project's top level folder (my_factory_install/..).

      This uses the myrepos tool to make it easier to work with multiple repositories.

      Note that one could instead decide to use google-repo tool instead to tackle the multiple repositories problem.

    And finally, a my_factory_install/env.sh helper script should be provided to quickly enter the factory install environment.

  4. For each supported device type, a my_factory_install/device-type/my_device_type script package should be defined.

    Replace my_device_type by your own device type. Note that it should match the device type used under my_device_config/device-type

    One can take this repos's ./device-type/virtual-box-vm package as an baseline.

    This nix package is responsible for bringing the hw-config-partition-and-format helper when installed on the target device.

    hw-config-partition-and-format is simply the customized way a device of a particular device type gets partitioned and formated.