Question, Need to Update the Linux apt Installation Instructions, Go All the Way or Keep it Simpler?

Edit: I found the code in openHABian that adds the keys and there’s a better way. I’ve updated the proposed changes below to use that. Also changed to /usr/share/keyrings instead of /usr/local/share/keyrings to conform to what openHABian does.

A minor issue came up with a small problem with the instructions on the website for apt based installation. For some reason, for some users, putting the URL to the PGP key in the wget doesn’t always work. It failed for me too once but worked a second time. :person_shrugging:

But in the process I found that apt-key is deprecated (probably not news to most of you but I use ansible to install everything so I don’t directly interact with these commands very often). We probably should not have instructions on our site that uses deprecated commands.

I spent some time looking around and I’m finding that the “best practices” is a little more involved than a one-liner wget.

The quick and dirty approach is to just download the pgp public key file, convert it to a gpg and drop it into /etc/trusted.gpg.d. I think that can still be a one-liner but it’s definitely a pretty long and complicated one so would make it a code block in the docs even if it could be done with pipes and ;. It can be written as a one liner.

The best practices approach, however, is to put the gpg file somewhere else (e.g. /usr/local/share/keyrings) and then inline in the openhab.list include [signed-by=/usr/share/keyrings/openhab.gpg].

The reason apt-key was deprecated was because apt is too trusting. Any package signed by that key would be accepted. By putting the keys somewhere else and adding the signed-by we can say “only trust this key for this specific repo and no others.”

@mstormi, I see that openHABian already does this the “best practices” way which is great to see.

So my question is, should we make the apt installation instructions tiny a bit more complicated to conform to best practices, or should we go half way and just drop the gpg file in apt’s trusted.gpg.d?

The current instructions are

First, add the openHAB repository key to your package manager:

wget -qO - '' | sudo apt-key add -

For the easy way that would change to:

First, add the openHAB repository key to your package manager:

curl -fsSL "" | gpg --dearmor > openhab.pgp | sudo mv openhab.pgp /usr/share/keyrings

Everything else would remain the same.

The best practices approach would become:

First, add the openHAB repository key to your package manager:

sudo mkdir /usr/share/keyrings
curl -fsSL "" | gpg --dearmor > openhab.pgp | sudo mv openhab.pgp /usr/share/keyrings

Then, you can choose between, Official (Stable), Beta or Snapshot builds:

  • Stable ReleaseThe stable builds contain the latest official release with tested features.Add the >openHAB Stable Repository to your systems apt sources list:
echo 'deb [signed-by=/usr/share/keyrings/openhab.gpg] stable main' | sudo tee /etc/apt/sources.list.d/openhab.list
  • Testing ReleaseThe beta and release candidate builds come out less frequently, but will contain new features that are currently in the testing phase.Add the openHAB Beta Repository to your systems apt sources list:
echo 'deb [signed-by=/usr/share/keyrings/openhab.gpg] testing main' | sudo tee /etc/apt/sources.list.d/openhab.list
  • Snapshot ReleaseThe snapshot build is created almost daily (opens new window), and include the latest changes to the openHAB core and add-ons. These changes are often unstable, so you should use this branch only for testing or development purposes.The snapshot repository is hosted in openHAB’s JFrog Artifactory instance (opens new window). To use it, add the openHAB Unstable Repository to your systems apt sources list:
echo 'deb [signed-by=/usr/share/keyrings/openhab.gpg] unstable main' | sudo tee /etc/apt/sources.list.d/openhab.list
1 Like

I would vote for having the best practice way in the docs.


I know this docs are only a proposal, so i don’t know if I can already test, but I did :slight_smile:
Used the “best practice” (you need sudo su for the first line, only sudo gives permission denied)

Found a typo in the docs (after this it is working):

First line: /usr/share/keyrings//openhab.pgp
Second line: signed-by=/usr/share/keyrings/openhab.gpg (stable)
Second line: signed-by=/usr/local/keyrings/openhab.gpg (testing)
Second line: signed-by=/usr/local/keyrings/openhab.gpg (snapshot)

So the first line should be: /usr/share/keyrings/openhab.pgp
And the second line: signed-by=/usr/share/keyrings/openhab.pgp

That must be something odd with your sudoers config. sudo means “run as root” and there is nothing special about mkdir unless the user you are running under is configured to only be allowed to sudo for certain commands.

Apparmor or SELinux might come into play too. What OS are you running?
Does the user you ran the mkdir command under have restricted sudo permissions? It seems odd to forbid mkdir but allow su.

Thanks for testing it out and finding the typo. It really helps.

I’ll leave this up for a day longer for further feedback and then submit a PR with the best practices way unless someone comes with arguments not to.

1 Like

Sorry, with the first line I ment this one:

curl -fsSL "" | sudo gpg --dearmor > "/usr/share/keyrings/openhab.pgp"

I’m running Debian 12 with nothing special in sudoers

Same thing applies. Just replace mkdir with gpg.

I’ve run this on several different machines and it’s never given an error. Maybe it’s a shell thing, I use fish instead of bash.


curl -fsSL "" | gpg --dearmor > openhab.pgp | sudo mv openhab.pgp /usr/share/keyrings

Im using bash, so that might be the problem?

-bash: /usr/share/keyrings/openhab.pgp: Permission denied
curl: (23) Failed writing body
curl -fsSL "" | gpg --dearmor > openhab.pgp | sudo mv openhab.pgp /usr/share/keyrings

This line is working without sudo su

Well, few people use anything except bash so it’s really me that has the problem. I need to find a way that works reliably in bash too.

I’m a little unhappy with the file permissions on the gpg file with that command. I think I still need some experimentation to get it right.

Thanks for testing this out!

PR can be found at Changed apt installation instructions gpg import by rkoshak · Pull Request #1845 · openhab/openhab-docs · GitHub