xbps/repositories/custom.md: document creating a repository

- xbps/repositories/signing.md was merged into custom.md with minor
  modifications
  - signing.md is now redirected to custom.md
- incorporates @camoz's change to show using 4096-bit RSA keys for signing

closes void-linux#641

Author: classabbyamp

book.toml

@@ -10,6 +10,7 @@ theme = "src/theme"
 [output.html.redirect]
 "/about-this-handbook.html" = "/about/about-this-handbook.html"
 "/config/man.html" = "/config/package-documentation/man.html"
+"/xbps/repositories/signing.html" = "/xbps/repositories/custom.html"
 
 [output.latex]
 optional = true

src/SUMMARY.md

@@ -76,7 +76,6 @@
          - [Using Tor Mirrors](./xbps/repositories/mirrors/tor.md)
       - [Restricted Packages](./xbps/repositories/restricted.md)
       - [Custom Repositories](./xbps/repositories/custom.md)
-      - [Signing Repositories](./xbps/repositories/signing.md)
    - [Troubleshooting XBPS](./xbps/troubleshooting/index.md)
       - [Common Issues](./xbps/troubleshooting/common-issues.md)
       - [Static XBPS](./xbps/troubleshooting/static.md)

src/xbps/repositories/custom.md

@@ -22,12 +22,90 @@ For example, to define a remote repository:
 # echo 'repository=http://my.domain.com/repo' > /etc/xbps.d/my-remote-repo.conf
 ```
 
-Remote repositories need to be [signed](./signing.md).
+Remote repositories need to be [signed](#signing-repositories-and-packages).
 [xbps-install(1)](https://man.voidlinux.org/xbps-install.1) refuses to install
 packages from remote repositories if they are not signed.
 
 To define a local repository:
 
 ```
-# echo 'repository=/path/to/repo' > /etc/xbps.d/my-local-repo.conf
+# echo 'repository=/path/to/repository/dir' > /etc/xbps.d/my-local-repo.conf
 ```
+
+## Signing repositories and packages
+
+Remote repositories **must** be signed. Local repositories do not need to be
+signed.
+
+The private key for signing packages needs to be a PEM-encoded RSA key. The key
+can be generated with either
+[ssh-keygen(1)](https://man.voidlinux.org/ssh-keygen.1) or
+[openssl(1)](https://man.voidlinux.org/openssl.1):
+
+```
+$ ssh-keygen -t rsa -b 4096 -m PEM -f private.pem
+```
+
+```
+$ openssl genrsa -out private.pem 4096
+```
+
+Once the key is generated, the public part of the private key has to be added to
+the repository metadata. This step is required only once.
+
+```
+$ xbps-rindex --privkey private.pem --sign --signedby "I'm Groot" /path/to/repository/dir
+```
+
+Then sign one or more packages with the following command:
+
+```
+$ xbps-rindex --privkey private.pem --sign-pkg /path/to/repository/dir/*.xbps
+```
+
+> Packages added to the repository index later will not be automatically signed.
+> Repeat the previous command to sign newly-added packages.
+
+## Manually maintaining repositories
+
+In many cases, `xbps-src` will handle the creation and addition of packages to a
+repository index, but the
+[xbps-rindex(1)](https://man.voidlinux.org/xbps-rindex.1) utility can also be
+used to manually manage xbps repositories. This can be useful if maintaining a
+repository of custom-built packages or using non-default build options.
+
+> When creating a repository for another architecture, prepend `xbps-rindex`
+> commands with `XBPS_TARGET_ARCH`. For example: `XBPS_TARGET_ARCH=armv7l-musl
+> xbps-rindex ...`
+
+### Adding packages to the repository index
+
+For xbps to know about a package, it must be added to the repository's index.
+Packages can be added to the repository index with `--add`:
+
+```
+$ xbps-rindex --add /path/to/repository/dir/*.xbps
+```
+
+### Cleaning the repository index
+
+When adding new versions of packages, `--remove-obseletes` can be used to purge
+the old version from both the repository index and remove the `.xbps` and `.sig`
+files from disk:
+
+```
+$ xbps-rindex --remove-obseletes /path/to/repository/dir
+```
+
+When removing a package from the repository, first remove the files from disk,
+then use `--clean` to remove the package from the repository index:
+
+```
+$ xbps-rindex --clean /path/to/repository/dir
+```
+
+### Serving remote repositories
+
+Remote repositories can be served by any HTTP daemon, like nginx or lighttpd, by
+configuring it to serve `/path/to/repository/dir` on the domain and path
+desired.