--- a/README.md Sun Dec 05 03:25:10 2021 -0600
+++ b/README.md Sun Dec 05 03:32:20 2021 -0600
@@ -3,7 +3,7 @@
[  ](https://issues.imfreedom.org/issues/HGKEEPER?u=1)
HGKeeper is an server for [mercurial](https://www.mercurial-scm.org/)
-repositories. It provides access control for SSH access and public HTTP+repositories. It provides access control for SSH access and public HTTP It was originally designed to be run in a container but recently support has
@@ -15,7 +15,7 @@
-This project is brand new and only lightly tested. If you find issues, or are+This project is brand new and only lightly tested. If you find issues, or are looking for ways to help, please check out our
[issue tracker](https://issues.imfreedom.org/issues/HGKEEPER?u=1).
@@ -39,19 +39,24 @@
-The initial setup of HGKeeper has a few steps. Since HGKeeper is an SSH server-you will need to generate host keys for it, as well as create the initial-`hgkeeper` repository which contains the configuration for your install.+The initial setup of HGKeeper has a few steps. +Since HGKeeper provides an SSH server you will need to generate host keys for +it if you are going to use it. You can skip the SSH server by passing +`--disable-ssh` or setting the `HGK_SSH_SERVER` environment variable to `true`. +This is useful if you just want to provide a read only repositories. You can generate SSH host keys for whatever type you like, but rsa will cover
-just about everyone. That said, a lot of people prefer to use ed25519 as well.+just about everyone. That said, a lot of people prefer to use ed25519 as well. By default the SSH host keys will be looked for in the directory `host-keys` in
-the current working directory. This can be changed with the `--ssh-host-keys-path` or `-H` command line arguments to hgkeeper.+the current working directory. This can be changed with the +`--ssh-host-keys-path` or `-H` command line arguments to hgkeeper. -This directory will be read and files in it will attempt to be loaded into the server.+This directory will be read and files in it will attempt to be loaded into the To generate a host key you can use the following command, note that you can
create other types via the `-t` option, but you should read the `ssh-keygen`
@@ -64,10 +69,10 @@
### Create the hgkeeper repo
Before you can run the server we need to create the `hgkeeper` admin
-repository. This can be done via `hgkeeper setup`. You will need to pass the+repository. This can be done via `hgkeeper setup`. You will need to pass the arguments `--admin-username` which is the name of the admin user, as well as
`--admin-pubkey` which is the path to the SSH public key for the new admin
-user. By default this will create a new repository under `repos/hgkeeper`.+user. By default this will create a new repository under `repos/hgkeeper`. There are some additional options which you can discover via
@@ -77,7 +82,7 @@
-The `setup` command is used to bootstrap HGKeeper. It will create the+The `setup` command is used to bootstrap HGKeeper. It will create the directory for the repositories as well as the `hgkeeper` repository.
After initial setup, please make sure to read the `README.md` in the `hgkeeper`
@@ -88,12 +93,26 @@
The `serve` command is the main mode of operation which is to provide access to
+You can optionally disable either one of the HTTP or SSH servers to limit +resources or just disable the portions you don't need. +For example, say you don't need public access or the web interface at all, you +can disable it by passing `--disable-http` to the `serve` command or by setting +the `HGK_DISABLE_HTTP` environment variable to `true`. +Likewise, if you just want to serve up a read only repositories over http you +can disable the SSH server by passing `--disable-ssh` to the `server` command +or by setting the `HGK_DISABLE_SSH` environment variable to `true`. +These two options are mutually exclusive and passing both will stop HGKeeper Access control is defined in the `hgkeeper` admin repository that is created
via the `hgkeeper setup` command. It is implemented via
[casbin](https://casbin.org) using the RBAC with deny-override model as a
-base. More information can be found in the [files](setup/resources/)+base. More information can be found in the [files](setup/resources/) that are placed in the `hgkeeper` admin repository.
## Running in a Container
@@ -113,7 +132,7 @@
repository by running the container with an overridden command.
An extra step to this is that you'll need to volume mount in a file containing
-the public key of the initial administrator of this instance. In the+the public key of the initial administrator of this instance. In the following example we assume that that key is in `~/.ssh/id_rsa.pub`.
Also, since this container is just used for initialization of files on the
@@ -142,7 +161,7 @@
The following example uses the same assumptions as the setup container above,
but it is also going to expose the container on the host's network interface.
The following example runs the container in the background, gives it a name of
-hgkeeper, and sets it to always restart. If you're just doing testing, you+hgkeeper, and sets it to always restart. If you're just doing testing, you will probably want to remove the `-d` (background), `--name hgkeeper` (name),
and `--restart=always` options.
@@ -159,22 +178,22 @@
-And that's it! You can now access your instance via the hosts IP address or+And that's it! You can now access your instance via the hosts IP address or DNS and you're good to go!
-Of course, you'll probably want to add some more users. To find out how to do+Of course, you'll probably want to add some more users. To find out how to do that, be sure to read the `README.md` in the `hgkeeper` admin repository.
Once the SSH host keys and the `hgkeeper` admin repository are created, you
-can run HGKeeper with `hgkeeper serve`. There are some other options that are+can run HGKeeper with `hgkeeper serve`. There are some other options that are available so be sure to check out `hgkeeper serve --help`.
## Running locally with an OpenSSH Server
There are a number of steps to integrate HGKeeper with OpenSSH Server and some
-of them vary across operating systems. If you run into a case where these+of them vary across operating systems. If you run into a case where these instructions do not work for you, please reach out via the issue tracker so we
can help you and fix the documentation.
@@ -195,26 +214,26 @@
To get HGKeeper fully running, you will need to run `hgkeeper setup` to create
-the `hgkeeper` admin repository as well as the initial admin user. Once this-repository is created, make sure it and it's parent directory are owned by the+the `hgkeeper` admin repository as well as the initial admin user. Once this +repository is created, make sure it and it's parent directory is owned by the `hg` user and that the `hg` user has write permission.
OpenSSH server has some very specific requirements for calling applications
-directly. These requirements are that the executable as well as all of the+directly. These requirements are that the executable as well as all of the directories leading up to the executable must be owned by root and not
-writeable by the group or other users. To deal with this, we will be-installing HGKeeper into `/usr/local/bin`. This directory should fulfill all-of the those requirements. So just `sudo cp hgkeeper /usr/local/bin/` and+writeable by the group or other users. To deal with this, we will be +installing HGKeeper into `/usr/local/bin`. This directory should fulfill all +of the those requirements. So just `sudo cp hgkeeper /usr/local/bin/` and make sure that it is owned by `root` with a file mode of `755`.
### Configuring OpenSSH Server
The OpenSSH configuration is actually quite easy, you just need to drop the
-following snippet into `/etc/ssh/sshd_config`. Of course, if you customized+following snippet into `/etc/ssh/sshd_config`. Of course, if you customized the install location or user name you'll have to adjust that in the snippet
-below. Note that the value for `--repos-path` needs to be the absolute path+below. Note that the value for `--repos-path` needs to be the absolute path You may be able to use `/etc/ssh/sshd_config.d/hgkeeper.conf` but in our
@@ -226,25 +245,25 @@
AuthorizedKeysCommandUser hg
-Once you've created the file, you'll need to reload OpenSSH Server. This is+Once you've created the file, you'll need to reload OpenSSH Server. This is usually done via `service ssh reload` but may vary based on your operating
Once you've reloaded OpenSSH Server you should be able to clone the `hgkeeper`
-admin repository with `hg clone ssh://hg@yourhostname/hgkeeper` as long the+admin repository with `hg clone ssh://hg@yourhostname/hgkeeper` as long as the machine you're cloning from has the private key that you added as your initial
## Creating Respositories
Creating a new repository in HGKeeper is just the same as using mercurial over
-SSH. That is, you can use the `hg init` command with a path to HGKeeper. As+SSH. That is, you can use the `hg init` command with a path to HGKeeper. As long as you have init permission for the path `HGKeeper` will create an empty
For example, if you wanted to create a new repository named
`myteam/new-project-1`, you would do so with
-`hg init ssh://hg@my-hgkeeper-domain/myteam/new-project-1`. If there were no+`hg init ssh://hg@my-hgkeeper-domain/myteam/new-project-1`. If there were no issues, the command will exit without error and you are now free to clone it
with `hg clone ssh://hg@my-hgkeeper-domain/myteam/new-project-1`.
@@ -252,12 +271,12 @@
### no mutual signature algorithm
-Fedora 33 disabled `ssh-rsa` by default in openssh-client. This breaks the+Fedora 33 disabled `ssh-rsa` by default in openssh-client. This breaks the golang `x/crypto/ssh` library. See
[this bug](https://github.com/golang/go/issues/37278) for more details.
The current work around for this is to add a host block in your ssh client
-configuration to re-enable `ssh-rsa`. See the following example:+configuration to re-enable `ssh-rsa`. See the following example: 