-
-
Notifications
You must be signed in to change notification settings - Fork 79
2.3 Athena Repository
Athena OS consists of several repositories for accessing to security tools and learning resources in a comfortable manner. They are core, extra, community and multilib stable Arch Linux repositories for system and utility packages, BlackArch repository for retrieving all the security tools, Chaotic repository for accessing to the AUR packages directly by pacman, and Athena repository, a remote repository where new tools or packages not stored in other existing repositories can be built and maintained. The structure of this repository is shown in https://github.com/Athena-OS/athena-repository and it is public for any contribution.
The source files of each single package is inside the packages directory. Each package has PKGBUILD file for defining the .pkg.tar.zst package rules and build.sh is used for automating this process by generating the new .pkg.tar.zst, signing it, moving it and its signature to x86_64 folder and delete all the temporary files.
When all packages are built, update-database.sh must be run for calling update_repo.sh script in order to update the athena-repository.db* files with the new built packages with .pkg.tar.zst extension stored in x86_64 folder.
The declaration of Athena repository is defined inside /etc/pacman.conf as:
[athena-repository]
SigLevel = Optional TrustedOnly
Server = https://athena-os.github.io/$repo/$arch
In Athena, the repository keys, athena.gpg, athena-trusted, athena-revoked, blackarch.gpg, blackarch-trusted, blackarch-revoked, chaotic.gpg, chaotic-trusted and chaotic-revoked files are stored in /usr/share/pacman/keyrings folder. athena.gpg file is the public key needed to be imported in order to access to Athena repository, athena-trusted contains the keys to trust, and athena-revoked contains the list of revoked keys in long format.
This operation is managed by Calamares installer that will initialize all the keys stored in /usr/share/pacman/keyrings folder.
During the ISO creation, it is possible to retrieve packages only from local or remote repositories accessible by pacman.
If the user needs to install custom packages at ISO creation process, it can create a custom local or remote repository.
Both of the methods require the creation of an environment where placing all files the package creation process needs. The user can create a directory named athena-repository with the structure shown in Athena GitHub repository: https://github.com/Athena-OS/athena-repository
Let's guess the user wants to create a package called 'dummy-menu'. In athena-repository/x84_64/packages folder, create the dummy-menu directory and inside it, put all the file tree you want to install in the target system and create a file named PKGBUILD a content similar to:
pkgname="dummy-menu"
pkgver="1.0.0"
pkgrel="1"
pkgdesc="Dummy Menu for Athena"
arch=("x86_64")
license=("custom")
source=("$pkgname.tar.gz")
package() {
mkdir -p "${pkgdir}/usr/share/icons/hicolor/128x128"
mkdir -p "${pkgdir}/usr/share/icons/hicolor/categories"
mkdir -p "${pkgdir}/usr/share/icons/shells"
mkdir -p "${pkgdir}/usr/share/pixmaps"
cp -rf "${srcdir}"/usr/share/icons/hicolor/128x128/* "${pkgdir}/usr/share/icons/hicolor/128x128/"
cp -rf "${srcdir}"/usr/share/icons/hicolor/categories/* "${pkgdir}/usr/share/icons/hicolor/categories/"
cp -rf "${srcdir}"/usr/share/icons/shells/* "${pkgdir}/usr/share/icons/shells/"
cp -rf "${srcdir}"/usr/share/pixmaps/* "${pkgdir}/usr/share/pixmaps/"
}
In package() function the user can write each command it prefers, except for some commands that cannot be executed as root, for example dconf, gsettings or makepkg.
For making the package file (a file with .zst extension), the user needs to execute makepkg command with some arguments. This process needs the user makes a tar.gz archive for the files to be added, creates some temporary files that can remain after the creation of the package. It is suggested to build a script that manages the creation of the package and the cleaning automatically, like the following build.sh script:
#!/bin/sh
#NEED ONLY TO EDIT sourcefiles VARIABLE
sourcefiles="usr"
pkgname=$(grep "^pkgname=" PKGBUILD | awk -F'"' '{print $2}')
pkgver=$(grep "^pkgver=" PKGBUILD | awk -F'"' '{print $2}')
pkgrel=$(grep "^pkgrel=" PKGBUILD | awk -F'"' '{print $2}')
arch=$(grep "^arch=" PKGBUILD | awk -F'"' '{print $2}')
pkgfile=$pkgname-$pkgver-$pkgrel-$arch.pkg.tar.zst
echo $pkgfile
sed -i '/^sha256/d' PKGBUILD
tar -zcvf $pkgname.tar.gz $sourcefiles
makepkg -g >> PKGBUILD
makepkg -f -scr --sign
rm -rf src pkg $pkgname.tar.gz
rm -rf ../../$pkgfile
mv $pkgfile $pkgfile.sig ../../In this example, the package file will be moved to the x86_64 directory that is the place where we store all our packages. In this way, when all the packages have been created or updated, the user can execute the update-database.sh script inside athena-repository folder for creating the .db file related to the created or updated packages. If the user retrieves packages from GitHub and customize them, remember to delete all git files (e.g., .git directory) and run git rm --cached x86_64/packages/<path-to-the-git-files> -f.
Note that inside build.sh, the makepkg command has --sign argument, so the package will be signed. If the user does not want to sign packages, it can remove that argument. If a signed package is needed, the user must create a private key that will be used for signing all the packages inside the user repository. A useful guide is the following: https://www.sainnhe.dev/post/create-personal-arch-linux-package-repository
In this guide, at the last section, is requested to publish the user repository to GitHub page. It is useful if the user wants to implement a remote repository.
For creating a GitHub Repository, go on the local folder where there are files to push:
$ git init
$ git branch -M main
$ git pull <--rebase> <link your repo.git>
$ git add --all
$ git commit -m "initial commit"
$ git remote add origin <link your repo.git>
$ git push
Just pay attention when you create the GitHub page: you must for first create index.md and _config.yaml files, that will be your home web page, on the root of your GitHub repository, and then the user should go to Settings of the repository → "Pages", set "main" as Branch and /root as folder and save this change as described in the guide, otherwise you risk to create a separate branch that is not connected with the files inside your GitHub repository. After this task, check on "Action" tab if the first deployment will end well.
At the end, go in airootfs/etc/pacman.conf and add:
[athena_repository]
SigLevel = Optional TrustedOnly
Server = file:///home/athena/$repo/$arch #In case of local repository or...
Server = https://athena-os.github.io/$repo/$arch #In case of remote repository
Remember to add the name of the created packages in packages.x86_64 file of archiso.
Important note: when the user makes any changes on its repository and push them on GitHub by git push, go on GitHub user webpage, in Actions section and monitor the running task. If the tasks fails, the user will see a red icon on it, and the user must fix that error otherwise the changes won't be applied on the remote repository. Usually, these errors are triggered by the presence of broken symbolic links inside the files of a package.
Furthermore, if a package in the repository is edited and the pkgver or pkgrel is not changed, when the end user executes pacman -Syu, cannot get the updated package. So, the developer should always change one of these two variables when a package is edited and delete the old .zstand .zst.sigfiles from x86_64folder and then execute update-db.sh. In case the developer does not update the version of the package, a workaround is that the end user should remove the package and reinstall it.
Sadly, it is not possible to retrieve packages directly from AUR during the ISO creation unless they are inside Chaotic AUR repository.
For installing AUR packages during the creation of ISO, the user must download package files of its desired package from AUR and make a package to be added in its custom repository. Some of the AUR packages added on Athena Repository are:
- firefox-esr-bin
- mkinitcpio-openswap
- powershell-bin
In Athena, for better managing the import and trust of the athena key and blackarch key, at the ISO creation phase, athena.gpg, athena-trusted, athena-revoked, blackarch.gpg, blackarch-trusted and blackarch-revoked files are stored in airootfs/usr/share/pacman/keyrings folder (blackarch key is stored by calling the ISO installation script). athena.gpg file is the public key we need to import, athena-trusted contains the keys to trust. and it has the following content:
<long-key>:4:
athena-revoked contains the list of revoked keys in long format.
After storing these files in keyrings folder, in general it is needed to perform:
sudo pacman-key --init
sudo pacman-key --populate
At the Athena ISO creation phase it is not needed because the trusted files have already been stored in airootfs/etc/pacman.d/gnupg in Archiso.
For exporting it in a file: gpg --export --armor --output athena-public.key A3F78B994C2171D5
For importing it in a new system:
pacman-key --add /etc/athena-public.key
or
sudo pacman-key --recv-keys A3F78B994C2171D5 --keyserver keys.openpgp.org
and, finally, trust it by:
sudo pacman-key --lsign A3F78B994C2171D5
gpg --export-secret-keys --armor --output privkey.asc user-id
Note: user-id can be specified with your key ID, fingerprint, a part of your name or email address.
In a new machine, you can import the private key in the following manner:
gpg --import privkey.asc
It will import also the public key. And then, if you need to sign packages, remember to edit /etc/makepkg.conf file.
Revocation certificates are automatically generated for newly generated keys. These are by default located in ~/.gnupg/openpgp-revocs.d/. The filename of the certificate is the fingerprint of the key it will revoke. The revocation certificates can also be generated manually by the user later using:
gpg --gen-revoke --armor --output revcert.asc user-id
Warning: if you import revcert.asc revocation certificate, your key will be revoked locally. If you send your revoked key to a public PGP server, it will be revoked globally. Once revoked, it is not possible to sign packages.
This certificate can be used to revoke a key if it is ever lost or compromised. The backup will be useful if you have no longer access to the secret key and are therefore not able to generate a new revocation certificate with the above command. It is short enough to be printed out and typed in by hand if necessary.
Warning: Anyone with access to the revocation certificate can revoke the key publicly, this action cannot be undone. Protect your revocation certificate like you protect your secret key.
Key revocation should be performed if the key is compromised, superseded, no longer used, or you forget your passphrase. This is done by merging the key with the revocation certificate of the key.
If you have no longer access to your keypair, first import a public key to import your own key. Then, to revoke the key, import the file saved in backup your revocation certificate:
$ gpg --import revcert.asc
Now the revocation needs to be made public. Use a keyserver to send the revoked key to a public PGP server if you used one in the past, otherwise, export the revoked key to a file and distribute it to your communication partners.
Source: https://wiki.archlinux.org/title/GnuPG#Backup_your_private_key
Run:
gpg --export <email address> | curl -T - https://keys.openpgp.org
Note: the email address is the one associated to the key to be uploaded.
Then, you will receive an email confirmation. Follow the instructions in the received email and your key should be uploaded in keys.openpgp.org keyserver.
You can verify it by running:
sudo pacman-key --recv-keys <key ID> --keyserver keys.openpgp.org