diff options
-rwxr-xr-x | configuration/debian/tedge/postinst | 27 | ||||
-rw-r--r-- | configuration/debian/tedge_agent/postinst | 23 | ||||
-rw-r--r-- | configuration/debian/tedge_mapper/postinst | 9 | ||||
-rw-r--r-- | docs/src/SUMMARY.md | 1 | ||||
-rw-r--r-- | docs/src/howto-guides/009_trouble_shooting_monitoring.md (renamed from docs/src/howto-guides/009_touble_shooting_monitoring.md) | 0 | ||||
-rw-r--r-- | docs/src/howto-guides/015_installation_without_deb_support.md | 72 | ||||
-rw-r--r-- | docs/src/howto-guides/README.md | 5 |
7 files changed, 110 insertions, 27 deletions
diff --git a/configuration/debian/tedge/postinst b/configuration/debian/tedge/postinst index 3744383a..08f36052 100755 --- a/configuration/debian/tedge/postinst +++ b/configuration/debian/tedge/postinst @@ -2,37 +2,42 @@ set -e ### Create groups -if ! getent group tedge-users > /dev/null; then +# thin-edge.io compoments run within their own groups and users the following steps add new groups if they don't exist. +if ! getent group tedge-users >/dev/null; then addgroup --quiet tedge-users fi -if ! getent group tedge > /dev/null; then +if ! getent group tedge >/dev/null; then addgroup --quiet --system tedge fi ### Create users # Create user tedge with no additional info(--gecos "") no home(--no-create-home), no login(--shell) and in group tedge(--ingroup) -if ! getent passwd tedge > /dev/null; then +if ! getent passwd tedge >/dev/null; then adduser --quiet --system --gecos "" --no-create-home --disabled-login --shell /sbin/nologin --ingroup tedge tedge fi -### Create folders +### Create directories +# thin-edge.io uses `/etc/tedge` directory as its main configuration directory. +# This directory contains mqtt bus configuration directory under `mosquitto-conf` +# and device certificates under `device-certs` so both have to be created in the directory structure. install -g tedge -o tedge -m 755 -d /etc/tedge install -g tedge -o tedge -m 755 -d /etc/tedge/mosquitto-conf -install -g tedge -o tedge -m 755 -d /var/log/tedge install -g mosquitto -o mosquitto -m 755 -d /etc/tedge/device-certs +# Create directory for logs +install -g tedge -o tedge -m 755 -d /var/log/tedge + ### Add include to mosquitto.conf so tedge specific conf will be loaded -if ! grep -q "/etc/tedge/mosquitto-conf" "/etc/mosquitto/mosquitto.conf" ; -then - echo "include_dir /etc/tedge/mosquitto-conf" >> /etc/mosquitto/mosquitto.conf +if ! grep -q "/etc/tedge/mosquitto-conf" "/etc/mosquitto/mosquitto.conf"; then + echo "include_dir /etc/tedge/mosquitto-conf" >>/etc/mosquitto/mosquitto.conf fi -### Create file in /etc/sudoers.d directory -echo "%tedge-users ALL = (ALL) /usr/bin/tedge" > /etc/sudoers.d/tedge-users +### Create file in /etc/sudoers.d directory. With this configuration, all users in the group tedge-users have the right to call the tedge command with sudo rights, which is required for system-wide configuration in "/etc/tedge" +echo "%tedge-users ALL = (ALL) /usr/bin/tedge" >/etc/sudoers.d/tedge-users if [ -f "/etc/sudoers.d/010_pi-nopasswd" ]; then - echo "%tedge-users ALL = (ALL) NOPASSWD: /usr/bin/tedge" > /etc/sudoers.d/tedge-users-nopasswd + echo "%tedge-users ALL = (ALL) NOPASSWD: /usr/bin/tedge" >/etc/sudoers.d/tedge-users-nopasswd fi ### Below are automatically created script parts by cargo deb (Search for cargo deb DEBHELPER) diff --git a/configuration/debian/tedge_agent/postinst b/configuration/debian/tedge_agent/postinst index b74c9262..fe466b69 100644 --- a/configuration/debian/tedge_agent/postinst +++ b/configuration/debian/tedge_agent/postinst @@ -2,31 +2,34 @@ set -e -# Create a group "tedge-agent" if not created before -if ! getent group tedge-agent > /dev/null; then +### Create a group "tedge-agent" if not created before +if ! getent group tedge-agent >/dev/null; then addgroup --quiet --system tedge-agent fi -# Create a user "tedge-agent" if not created before -if ! getent passwd tedge-agent > /dev/null; then +### Create a user "tedge-agent" if not created before +# Create user tedge-agent with no home(--no-create-home), no login(--shell) and in group tedge-agent(--ingroup) +if ! getent passwd tedge-agent >/dev/null; then adduser --quiet --system --no-create-home --ingroup tedge-agent --shell /usr/sbin/nologin tedge-agent fi ### Create file in /etc/sudoers.d directory -echo "%tedge-agent ALL = (ALL) NOPASSWD: /etc/tedge/sm-plugins/[a-zA-Z0-9]*" > /etc/sudoers.d/tedge-agent +# tedge-agent needs to execute some of its operations as a system user therefore it needs an entry in /etc/sudoers. +echo "%tedge-agent ALL = (ALL) NOPASSWD: /etc/tedge/sm-plugins/[a-zA-Z0-9]*" >/etc/sudoers.d/tedge-agent if [ -f "/etc/sudoers.d/010_pi-nopasswd" ]; then - echo "%tedge-agent ALL = (ALL) NOPASSWD: /etc/tedge/sm-plugins/[a-zA-Z0-9]*" > /etc/sudoers.d/tedge-agent-nopasswd + echo "%tedge-agent ALL = (ALL) NOPASSWD: /etc/tedge/sm-plugins/[a-zA-Z0-9]*" >/etc/sudoers.d/tedge-agent-nopasswd fi -# create /etc/tedge/.agent directory +### Create directories +# Create tedge-agent state directory /etc/tedge/.agent install -g tedge-agent -o tedge-agent -m 754 -d /etc/tedge/.agent -# create /var/log/tedge/agent directory +# Create /var/log/tedge/agent directory install -g tedge-agent -o tedge-agent -m 755 -d /var/log/tedge/agent -## Enable the sm services if the device is connected to c8y cloud -if [ -f "/etc/tedge/mosquitto-conf/c8y-bridge.conf" ]; then +### Enable the sm services if the device is connected to c8y cloud +if [ -f "/etc/tedge/mosquitto-conf/c8y-bridge.conf" ]; then # start and enable tedge-agent systemctl start tedge-agent.service systemctl enable tedge-agent.service diff --git a/configuration/debian/tedge_mapper/postinst b/configuration/debian/tedge_mapper/postinst index 8140695e..17e45367 100644 --- a/configuration/debian/tedge_mapper/postinst +++ b/configuration/debian/tedge_mapper/postinst @@ -2,13 +2,14 @@ set -e -# Create a group "tedge-mapper" if not created before -if ! getent group tedge-mapper > /dev/null; then +### Create a group "tedge-mapper" if not created before +if ! getent group tedge-mapper >/dev/null; then addgroup --quiet --system tedge-mapper fi -# Create a user "tedge-mapper" if not created before -if ! getent passwd tedge-mapper > /dev/null; then +### Create a user "tedge-mapper" if not created before +# Create user tedge-mapper with no home(--no-create-home), no login(--shell) and in group tedge(--ingroup) +if ! getent passwd tedge-mapper >/dev/null; then adduser --quiet --system --no-create-home --ingroup tedge-mapper --shell /usr/sbin/nologin tedge-mapper fi diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 7b71d1ff..35d18415 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -26,6 +26,7 @@ - [How to install and enable software management?](./howto-guides/012_install_and_enable_software_management.md) - [How to connect an external device?](./howto-guides/013_connect_external_device.md) - [How to access the logs on the device?](./howto-guides/014_thin_edge_logs.md) + - [How to install thin-edge.io on any Linux OS (no deb support)?](./howto-guides/015_installation_without_deb_support.md) ## Reference guides diff --git a/docs/src/howto-guides/009_touble_shooting_monitoring.md b/docs/src/howto-guides/009_trouble_shooting_monitoring.md index 21a5ca2e..21a5ca2e 100644 --- a/docs/src/howto-guides/009_touble_shooting_monitoring.md +++ b/docs/src/howto-guides/009_trouble_shooting_monitoring.md diff --git a/docs/src/howto-guides/015_installation_without_deb_support.md b/docs/src/howto-guides/015_installation_without_deb_support.md new file mode 100644 index 00000000..65e2d023 --- /dev/null +++ b/docs/src/howto-guides/015_installation_without_deb_support.md @@ -0,0 +1,72 @@ +# How to install `thin-edge.io` on any Linux OS (no deb support)? + +## `thin-edge.io` on supported platforms + +`thin-edge.io` can be installed on a range of platforms, a platform is defined as a set of hardware architecture and OS, more details can be found in [Supported Platforms](../supported-platforms.md) document. + +Out of the box `thin-edge.io` uses deb packages for an automated installation ([Installation Guide](./002_installation.md)), you can install it yourself on any Linux system as long as you follow the guidelines below. + +## Installation on 'unsupported platforms' + +### Obtaining binaries + +The prebuilt binaries can be obtained from `thin-edge.io` [repository releases](https://github.com/thin-edge/thin-edge.io/releases). + +By default `thin-edge.io` is built with 3 architectures in mind: `amd64 (x86_64)`, `arm64 (aarch64)` and `armhf` with gnulibc bindings, so if you are looking to install `thin-edge.io` on a different platform you have to build your own binaries from source which you can do easily if you follow the [Building `thin-edge.io`](../../../BUILDING.md) guide. + +> Note: By default `thin-edge.io` is built with `GNU libc`, but it is possible to use `musl` instead. + +Full installation of `thin-edge.io` requires the following components: + +* tedge +* tedge-mapper +* tedge-agent + +#### Extracting binaries from deb packages + +> Required packages: +> +> * ar +> * tar + +Currently all binaries provided with releases are packaged into `deb` packages. +`deb` packages can be extracted to get the binaries for installation (example): + +```shell +ar -x tedge_<version>_amd64.deb | tar -xf data.tar.xz +ar -x tedge_agent_<version>_amd64.deb | tar -xf data.tar.xz +ar -x tedge_mapper_<version>_amd64.deb | tar -xf data.tar.xz +``` + +Which should give you `usr` and/or `lib` directory where you can find binaries. +After extracting all packages, you should now adjust permissions on those files: + +```shell +chown root:root /usr/bin/tedge +chown root:root /usr/bin/tedge_agent +chown root:root /usr/bin/tedge_mapper +``` + +and then move your binaries to the appropriate directory, eg: + +```shell +mv ./lib/ ./bin/ / +``` + +#### If building from source + +If you have built the binaries from source you should install them on the target in: `/usr/bin/`. + +`systemd` unit files for `tedge_mapper` and `tedge_agent` can be found in the repository at `configuration/init/systemd/tedge-*` and should be installed on the target in: `lib/systemd/system/tedge-*`. + +### Configuring the system and systemd-units + +`thin-edge.io` relies on certain system configuration and systemd process management, when installing from deb package all of that is setup automatically but with manual installation a set of steps has to be performed. + +On most Linux distribution it should suffice to execute them as `root` to do the setup, but in some cases (eg, your system uses `useradd` instead of `adduser` package) more detailed instructions are documented: + +* [tedge](../../../configuration/debian/tedge/postinst) +* [tedge-agent](../../../configuration/debian/tedge_agent/postinst) +* [tedge-mapper](../../../configuration/debian/tedge_mapper/postinst) + +After following steps for all the components installed `thin-edge.io` should be operational. diff --git a/docs/src/howto-guides/README.md b/docs/src/howto-guides/README.md index e7c883e6..05b43fd3 100644 --- a/docs/src/howto-guides/README.md +++ b/docs/src/howto-guides/README.md @@ -7,9 +7,10 @@ 5. [How to test connection to cloud?](./007_test_connection.md) 6. [How to test the cloud connection?](./007_test_connection.md) 7. [How to configure the local mqtt port?](./008_config_local_mqtt_port.md) -8. [How to trouble shoot device monitoring?](./009_touble_shooting_monitoring.md) +8. [How to trouble shoot device monitoring?](./009_trouble_shooting_monitoring.md) 9. [How to add self-signed certificate root to trusted certificates list?](./010_add_self_signed_trusted.md) 10. [How to retrieve JWT token from Cumulocity?](./011_retrieve_jwt_token_from_cumulocity.md) 11. [How to install and enable software management?](./012_install_and_enable_software_management.md) 12. [How to connect an external device?](./013_connect_external_device.md) -14. [How to access the logs on the device?](./014_thin_edge_logs.md) +13. [How to access the logs on the device?](./014_thin_edge_logs.md) +14. [How to install thin-edge.io on any Linux OS (no deb support)?](./015_installation_without_deb_support.md) |