Stork Quickstart guide
- 29 Dec 2023
- 14 Minutes to read
-
Contributors
-
Print
-
DarkLight
-
PDF
Stork Quickstart guide
- Updated on 29 Dec 2023
- 14 Minutes to read
-
Contributors
-
Print
-
DarkLight
-
PDF
Article Summary
Share feedback
Thanks for sharing your feedback!
Introduction
Installing Stork can seem somewhat confusing at first. The purpose of this quickstart guide is to layout the installation process in steps grouped by package manager or OS. Choose your OS/package manager from the table of contents on the right hand side to jump directly to the section that will cover the installation on your system.
Stork Agent
Since the Stork Agent may need to be installed more than once on disparate systems (example: to monitor BIND and Kea installations which typically may not reside on the same servers), more than one section may need to be visited for the Stork Agent installation.
The Stork packages themselves will be sourced from our repositories on cloudsmith.io.
This guide was updated as of Stork version 1.11.0. Using earlier versions of Stork with this guide may not result in success.
RedHat (RPM compatible)
This section covers installing on systems that use the RPM package manager. These could be RedHat Enterprise Linux, CentOS, Fedora, Rocky Linux, or any other RedHat based system (or clone) that uses the rpm command.
Adding the Stork repository
First add the Stork cloudsmith.io repository to the system:
curl -1sLf 'https://dl.cloudsmith.io/public/isc/stork/cfg/setup/bash.rpm.sh' | sudo bash
Output should be shown similar to the following
Executing the setup script for the 'isc/stork' repository ...
OK: Checking for required executable 'curl' ...
OK: Checking for required executable 'rpm' ...
OK: Detecting your OS distribution and release using system methods ...
^^^^: ... Detected/provided for your OS/distribution, version and architecture:
>>>>:
>>>>: ... distro=rocky version=9.2 codename=Blue arch=x86_64
>>>>:
OK: Importing 'isc/stork' repository GPG keys into rpm ...
OK: Checking for available package manager (DNF/Microdnf/YUM/Zypper) ...
^^^^: ... Detected package manager as 'dnf'
OK: Checking for dnf dependency 'dnf-plugins-core' ...
OK: Checking if upstream install config is OK ...
OK: Fetching 'isc/stork' repository configuration ...
OK: Installing 'isc/stork' repository via dnf ...
RUN: Updating the dnf cache to fetch the new repository metadata ...Importing GPG key 0x8053D1FB:
Userid : "Cloudsmith Package (isc/stork) <support@cloudsmith.io>"
Fingerprint: 7AB5 064B 08F0 69A1 A5CC 500C 77F6 4EC2 8053 D1FB
From : https://dl.cloudsmith.io/public/isc/stork/gpg.77F64EC28053D1FB.key
Importing GPG key 0x8053D1FB:
Userid : "Cloudsmith Package (isc/stork) <support@cloudsmith.io>"
Fingerprint: 7AB5 064B 08F0 69A1 A5CC 500C 77F6 4EC2 8053 D1FB
From : https://dl.cloudsmith.io/public/isc/stork/gpg.77F64EC28053D1FB.key
Importing GPG key 0x8053D1FB:
Userid : "Cloudsmith Package (isc/stork) <support@cloudsmith.io>"
Fingerprint: 7AB5 064B 08F0 69A1 A5CC 500C 77F6 4EC2 8053 D1FB
From : https://dl.cloudsmith.io/public/isc/stork/gpg.77F64EC28053D1FB.key
OK: Updating the dnf cache to fetch the new repository metadata ...
OK: The repository has been installed successfully - You're ready to rock!
Related section in the Stork ARM.
Installing the Stork Server
Next, install the Stork server. This only needs to be done on the system from which you will actually serve the Stork web UI.
sudo dnf install isc-stork-server
The usual RPM output should be shown here successfully installing the "isc-stork-server" package.
Related section in the Stork ARM.
Configuring the database
The next step is to configure the database for use by the Stork web based UI. Stork requires PostgreSQL. Be sure you have that installed and running. The stork-tool which is included with the "isc-stork-server" package is used to create the database as shown.
sudo su - postgres
stork-tool db-create --db-name stork --db-user stork-server
Output similar to the following should be printed to the terminal.
INFO[2023-05-22 11:27:53] connection.go:90 Checking connection to database
INFO[2023-05-22 11:27:53] connection.go:145 Connected to database /var/run/postgresql/.s.PGSQL.5432
INFO[2023-05-22 11:27:53] connection.go:90 Checking connection to database
INFO[2023-05-22 11:27:53] connection.go:145 Connected to database /var/run/postgresql/.s.PGSQL.5432
INFO[2023-05-22 11:27:53] main.go:115 Created database and user for the server with the following credentials database_name="stork" password="WgzoENQyr2oPgNkKN64UbHejD6vASCpo" user="stork-server"
If an error is shown something like this:
FATA[2023-05-22 11:24:26] main.go:111 Cannot create the database extension error="problem creating database extension \"pgcrypto\": ERROR #58P01 could not open extension control file \"/usr/share/pgsql/extension/pgcrypto.control\": No such file or directory"
Then you may need to install the postgres contrib package as shown.
sudo dnf install postgresql-contrib
Then retry the stork-tool command.
Related section in the Stork ARM.
Configuring the Stork Server
Next up is configuring the Stork server configuration file. Assuming the PostgreSQL database service and the Stork web UI service are on the same server and the previous stork-tool command line was executed as noted in the earlier instructions, there is very little that must be changed in /etc/stork/server.env. Edit that file with your favorite command line text editor. The only change needed is to uncomment the line that contains STORK_DATABASE_USER_NAME and set the username to stork-server as shown: STORK_DATABASE_USER_NAME=stork-server.
Related section in the Stork ARM.
Starting the Stork Server
Next, the server must be enabled and started in systemd. Enable the Stork server:
sudo systemctl enable isc-stork-server
Start the Stork server:
sudo systemctl start isc-stork-server
Now check the status to make sure it is running correctly:
sudo systemctl status isc-stork-server
Now you should be able to connect to the web interface using the http://IP_address_of_your_server:8080 (example: http://192.168.20.27:8080). If it doesn't answer, you may need to investigate firewall rules. Some recent RedHat (and compatible), by default, run firewalld which may block this connection. Find out if that is the problem by running sudo systemctl stop firewalld. If you can now connect to the web service, then rules in firewalld will need to be added to allow connection. Configuration of this service is beyond the scope of this document.
The default username and password are admin/admin. After logging in, this should be changed by clicking the down arrow in the upper right corner and clicking "Profile". Then click on "Change Password" on the resulting screen. Follow the steps there to change the admin password.
Related section in the Stork ARM.
Installing the Stork Agent
The final step is to install the Stork Agent on any systems where you wish to monitor ISC servers. Currently, the Stork Agent is capable of monitoring both Kea and BIND. It should auto-detect these servers and may start monitoring them with little intervention on your part.
To install the Stork Agent, add the repository to any RedHat/RPM compatible system where you want to monitor these services in the same manner as performed earlier:
curl -1sLf 'https://dl.cloudsmith.io/public/isc/stork/cfg/setup/bash.rpm.sh' | sudo bash
Now install the Stork Agent in this way:
sudo dnf install isc-stork-agent
which should produce the usual RPM messages about the installation.
Now enable the Stork Agent using systemctl as shown.
sudo systemctl enable isc-stork-agent
Now start the agent.
sudo systemctl start isc-stork-agent
Make sure the Stork Agent is running using status.
sudo systemctl status isc-stork-agent
Related section in the Stork ARM.
Stork Server and Stork Agent cohabitating
Please note that if the Stork Server and Stork Agent are both on the same machine, that they both default to port 8080. The easiest thing to do is alter /etc/stork/agent.env uncommenting the "STORK_AGENT_PORT" directive and setting thusly: STORK_AGENT_PORT=8081. This way, the agent will listen on port 8081 and the server will listen on port 8080 as per default.
Register Stork Agent
Once the Stork Agent is confirmed to be running, the agent must be registered with the Stork server. Execute the registeration command as shown on the server with the stork-agent installed.
sudo su stork-agent -s /bin/sh -c 'stork-agent register --server-url http://stork.example.org:8080'
where "stork.example.org" is replaced with the name or IP of the server running the Stork server. Accepting the defaults is fine.
Altered Stork Agent Port
If you had to alter the Stork Agent Port to 8081 due to cohabitation with the Stork Server, then you will have to specify the port number during the registration process as shown here: >>>> Port number that Stork Agent will listen on [8080]: 8081
Once the process completes, the agent must be authorized on the Stork server. Visit Services -> Machines and then click on Unauthorized. The server with the Stork agent should be shown here. Click the hamburger menu and click Authorize. Click the Authorized tab to make sure that this succeeded. If this fails, showing a message like this:
it may be due to firewalld. Try stopping firewalld sudo systemctl stop firewalld on the server with the Stork agent installed and then click the hamburger menu in the Stork web UI and click refresh. If this works, then firewalld rules will need adjustment going forward. Configuration of firewalld is beyond the scope of this document.
Check the web interface. New options should have appeared under the "DHCP" menu. If nothing new appears, try refreshing the browser window.
Monitoring BIND 9
If only DHCP options appear in the Stork web UI, it is possible that BIND is not being monitored. If you do not have an rndc.conf file, this can be the case. Set this up using rndc-confgen which will print out rndc.conf configurations. Place these in an rndc.conf file in the same directory as named.conf. There is a commented out section similar to:
# Use with the following in named.conf, adjusting the allow list as needed:
# key "rndc-key" {
# algorithm hmac-sha256;
# secret "TTWW+Lf1KElICDFOc8nShvlMb1vvFPDnW1wz8afHjfI=";
# };
#
# controls {
# inet 127.0.0.1 port 953
# allow { 127.0.0.1; } keys { "rndc-key"; };
# };
# End of named.conf
Place this in the named.conf file and uncomment the key and controls sections. Restart named and Stork should be monitoring BIND.
Additional permissions may be needed
The Stork agent may also need access to named.conf and rndc.conf which it may not be able to access by default. Find these files and confirm that "other" has read access to them. For example:
$ ls -alFh /etc/opt/isc/scls/isc-bind/rndc.conf
-rw-r--r--. 1 root root 525 Jun 7 15:16 /etc/opt/isc/scls/isc-bind/rndc.conf
notice the third 'r' shown in the permissions. Keep an eye out for other permission denied error messags in the stork-agent logs. It is really difficult to predict what permissions issues might be encountered without knowing the source of the BIND installation (official ISC packages, distro specific packages, or compiled from source).
Related section in the Stork ARM.
Debian (apt compatible)
This section covers installing on systems that use the apt (.deb) package manager. These could be Debian, Ubuntu, Knoppix, Linux Mint, or any other Debian based system that uses the apt command.
Adding the Stork repository
First add the Stork cloudsmith.io repository to the system:
curl -1sLf 'https://dl.cloudsmith.io/public/isc/stork/cfg/setup/bash.deb.sh' | sudo bash
Output should be shown similar to the following:
Executing the setup script for the 'isc/stork' repository ...
OK: Checking for required executable 'curl' ...
OK: Checking for required executable 'apt-get' ...
OK: Detecting your OS distribution and release using system methods ...
^^^^: ... Detected/provided for your OS/distribution, version and architecture:
>>>>:
>>>>: ... distro=debian version=11 codename=bullseye arch=x86_64
>>>>:
NOPE: Checking for apt dependency 'apt-transport-https' ...
OK: Updating apt repository metadata cache ...
OK: Attempting to install 'apt-transport-https' ...
OK: Checking for apt dependency 'ca-certificates' ...
NOPE: Checking for apt dependency 'gnupg' ...
OK: Attempting to install 'gnupg' ...
OK: Checking for apt signed-by key support ...
OK: Importing 'isc/stork' repository GPG keys ...
OK: Checking if upstream install config is OK ...
OK: Installing 'isc/stork' repository via apt ...
OK: Updating apt repository metadata cache ...
OK: The repository has been installed successfully - You're ready to rock!
Related section in the Stork ARM.
Installing the Stork Server
Next, install the Stork server. This only needs to be done on the system from which you will actually serve the Stork web UI.
sudo apt install isc-stork-server
The usual apt install output should be shown here.
Related section in the Stork ARM.
Configuring the database
The next step is to configure the database for use by the Stork web based UI. Stork requires PostgreSQL. Be sure you have that installed and running. The stork-tool which is included with the "isc-stork-server" package is used to create the database as shown.
sudo su - postgres
stork-tool db-create --db-name stork --db-user stork-server
Output similar to the following should be printed to the terminal.
INFO[2023-05-24 16:31:39] connection.go:90 Checking connection to database
INFO[2023-05-24 16:31:39] connection.go:145 Connected to database /var/run/postgresql/.s.PGSQL.5432
INFO[2023-05-24 16:31:39] connection.go:90 Checking connection to database
INFO[2023-05-24 16:31:39] connection.go:145 Connected to database /var/run/postgresql/.s.PGSQL.5432
INFO[2023-05-24 16:31:39] main.go:115 Created database and user for the server with the following credentials database_name="stork" password="hwF8XOSoLZn+r63gLHNirl2yJJbb0Q8N" user="stork"
Related section in the Stork ARM.
Configuring the Stork Server
Next up is configuring the Stork server configuration file. Assuming the PostgreSQL database service and the Stork web UI service are on the same server and the previous stork-tool command line was executed as noted in the earlier instructions, there is very little that must be changed in /etc/stork/server.env. Edit that file with your favorite command line text editor. The only change needed is to uncomment the line that contains STORK_DATABASE_USER_NAME and set the username to stork-server as shown: STORK_DATABASE_USER_NAME=stork-server.
Related section in the Stork ARM.
Starting the Stork Server
Next, the server must be enabled and started in systemd. Enable the Stork server:
sudo systemctl enable isc-stork-server
Start the Stork server:
sudo systemctl start isc-stork-server
Now check the status to make sure it is running correctly:
sudo systemctl status isc-stork-server
Now you should be able to connect to the web interface using the http://IP_address_of_your_server:8080 (example: http://192.168.20.27:8080). The default username and password are admin/admin. After logging in, this should be changed by clicking the down arrow in the upper right corner and clicking "Profile". Then click on "Change Password" on the resulting screen. Follow the steps there to change the admin password.
Related section in the Stork ARM.
Installing the Stork Agent
The final step is to install the Stork Agent on any systems where you wish to monitor ISC servers. Currently, the Stork Agent is capable of monitoring both Kea and BIND. It should auto-detect these servers and may start monitoring them with little intervention on your part.
To install the Stork Agent, add the repository to any apt/.deb compatible system where you want to monitor these services in the same manner as performed earlier:
curl -1sLf 'https://dl.cloudsmith.io/public/isc/stork/cfg/setup/bash.deb.sh' | sudo bash
Now install the Stork Agent:
sudo apt install isc-stork-agent
which should produce normal apt messages during the installation.
Now enable the Stork Agent using systemctl.
sudo systemctl enable isc-stork-agent
Then start the agent.
sudo systemctl start isc-stork-agent
Make sure the Stork Agent is running properly using status.
sudo systemctl status isc-stork-agent
Related section in the Stork ARM.
Stork Server and Stork Agent cohabitating
Please note that if the Stork Server and Stork Agent are both on the same machine, that they both default to port 8080. The easiest thing to do is alter /etc/stork/agent.env uncommenting the "STORK_AGENT_PORT" directive and setting thusly: STORK_AGENT_PORT=8081. This way, the agent will listen on port 8081 and the server will listen on port 8080 as per default.
Register Stork Agent
Once the Stork Agent is confirmed to be running, the agent must be registered with the Stork server. Execute the registeration command as shown on the server with the stork-agent installed.
sudo su stork-agent -s /bin/sh -c 'stork-agent register --server-url http://stork.example.org:8080'
where "stork.example.org" is replaced with the name or IP of the server running the Stork server. Accepting the defaults is fine.
Altered Stork Agent Port
If you had to alter the Stork Agent Port to 8081 due to cohabitation with the Stork Server, then you will have to specify the port number during the registration process as shown here: >>>> Port number that Stork Agent will listen on [8080]: 8081
Once the process completes, the agent must be authorized on the Stork server. Visit Services -> Machines and then click on Unauthorized. The server with the Stork agent should be shown here. Click the hamburger menu and click Authorize.
Check the web interface. New options should have appeared under the "DHCP" menu. If nothing new appears, try refreshing the browser window.
Monitoring BIND 9
If only DHCP options appear in the Stork web UI, it is possible that BIND is not being monitored. If you do not have an rndc.conf file, this can be the case. Set this up using rndc-confgen which will print out rndc.conf configurations. Place these in an rndc.conf file in the same directory as named.conf. There is a commented out section similar to:
# Use with the following in named.conf, adjusting the allow list as needed:
# key "rndc-key" {
# algorithm hmac-sha256;
# secret "TTWW+Lf1KElICDFOc8nShvlMb1vvFPDnW1wz8afHjfI=";
# };
#
# controls {
# inet 127.0.0.1 port 953
# allow { 127.0.0.1; } keys { "rndc-key"; };
# };
# End of named.conf
Place this in the named.conf file and uncomment the key and controls sections. Restart named and Stork should be monitoring BIND.
Additional permissions may be needed
The Stork agent may also need access to named.conf and rndc.conf which it may not be able to access by default. Find these files and confirm that "other" has read access to them. For example:
$ ls -alFh /etc/opt/isc/scls/isc-bind/rndc.conf
-rw-r--r--. 1 root root 525 Jun 7 15:16 /etc/opt/isc/scls/isc-bind/rndc.conf
notice the third 'r' shown in the permissions. Keep an eye out for other permission denied error messags in the stork-agent logs. It is really difficult to predict what permissions issues might be encountered without knowing the source of the BIND installation (official ISC packages, distro specific packages, or compiled from source).
Related section in the Stork ARM.