Administering a hub
Administrator profiles, accounts, invitations and scopes
Someone on a team has to decide who may log in to its private hub, and who may publish under which names. That person is the hub's administrator. This chapter is for them. It covers the administrator's connection, accounts, invitations and scopes. The hub itself (the server, its storage, its backups) is run for you by Frogfish, so none of that appears here: you look after the people and the names, not the machine.
What you will be able to do
- Save your administrator connection once, and switch between hubs.
- Add accounts and invite people, with a code or a download link.
- Suspend, reactivate and delete accounts.
- Give a scope to an account, look scopes up, and take them away.
Two kinds of credential
An ordinary login (from gritpack login) lets an account search, install and
publish. It cannot manage the hub. Administration uses a separate
administrator certificate, issued for the hub's management address, which
is different from the address packages come from. The hub accepts the two
from different authorities, so a publishing credential can never be used to
administer, however it was obtained.
When your hub is set up, Frogfish gives the administrator:
| Item | What it is |
|---|---|
| the management address | host:port for administration, for example packages.example.com:7444 |
admin.pem | the administrator certificate; not secret by itself |
admin-key.pem | its private key; secret: keep it as you would a password |
| a CA file | the certificate authority that vouches for the hub |
Every gritpack admin command takes these four as --hub, --cert, --key
and --ca. Typing them each time is tedious, so save them as a profile.
Administrator profiles
gritpack admin profile add saves the four under a name:
$ gritpack admin profile add team --hub packages.example.com:7444 \
--cert admin.pem --key admin-key.pem --ca server-ca.pem
saved administrator profile team (the default) in ~/.frogfish/gritpack/admin.toml
The first profile becomes the default, so from now on gritpack admin ...
needs no connection flags at all. The profile records where the files are;
it does not copy them. Keep admin-key.pem where it is, readable only by
you.
With more than one hub, add a profile for each and choose between them:
$ gritpack admin profile list
other packages.example.com:7444 cert=.../admin.pem
* team packages.example.com:7444 cert=.../admin.pem
$ gritpack admin profile use other
administrator commands now use other by default
$ gritpack admin user list --profile team
...
$ gritpack admin profile remove other
removed administrator profile other; its certificate and key files are untouched
The * marks the default. --profile on any admin command picks one for that
command. A flag given on the command line wins over the profile, so
--hub with a different address still works for a one-off.
If you remove the default profile, no profile is the default any more, and
admin commands ask for connection flags until you run admin profile use
again.
Administrator profiles live in ~/.frogfish/gritpack/admin.toml, apart from
your logins in config.toml. GRITPACK_ADMIN_CONFIG points at another file,
and GRITPACK_ADMIN_PROFILE chooses a profile. Without any profile, the
variables GRITPACK_MANAGEMENT_SERVER, GRITPACK_ADMIN_CERT,
GRITPACK_ADMIN_KEY and GRITPACK_CA supply the connection.
Careful. Anyone with your administrator key can add accounts, give away scopes and hide packages on your hub. Do not put it in a shared folder, a repository or a CI secret that pull requests can read. If it leaks, ask Frogfish to replace it.
Accounts
An account is an email address. It exists on the hub before its owner ever logs in:
$ gritpack admin user add sam@example.com
account=01a1e867-b1f6-7c20-a6ad-fd28f53e0615 email=sam@example.com
Adding an account does not let anyone in. For that, the person needs an invitation.
Inviting someone
$ gritpack admin user invite sam@example.com
invitation=01a1e867-b267-75b1-9444-c2ca310ec7dc account=01a1e867-b1f6-7c20-a6ad-fd28f53e0615 expires_at=1794986872 enrollment_code=E770-0DFB-80CB-4F19-A197-2417
Send the person the enrollment_code and your hub's address. They run:
gritpack login sam@example.com --hub packages.example.com --code E770-0DFB-80CB-4F19-A197-2417
Logging in walks through it from their side. The code:
- works once, and only together with the invited email address;
- expires after 24 hours (
expires_atis a Unix time); - is not stored on the hub, only a digest of it, so even the hub cannot show it to you again. If it is lost, invite again.
Send it by a channel you trust. Inviting again does not cancel an earlier invitation; revoke one you no longer want (below).
People renew their login every 30 days with gritpack auth renew, and that
also needs a fresh code. Expect to invite each person once a month. An
account whose login has expired is invited the same way as a new one.
An invitation as a link
Instead of a code, an invitation can be a link to a download that installs Gritpack if needed and logs the person in with one click. Give the hub's public enrollment and package addresses:
$ gritpack admin user invite kim@example.com --download \
--enrollment-hub packages.example.com:7445 --package-hub packages.example.com:443
invitation=01a1e868-2a81-7592-a3a5-05f43591beb1 account=01a1e868-2a01-7272-abd4-9bce784b9037 expires_at=1794986903 link=https://get.gritpack.org/i/1NP3Z0QZ7X
The link's last part is the code, ten characters long. The page it opens
offers a Mac download and, for Linux and Mac terminals, a one-line install
that carries the code. The person sees which hub and which email they are
joining before anything happens. The link works once and expires with the
invitation. --title names the download ("Join ..." by default),
--invitee-profile names the login profile it creates, and --download-hub
chooses the hub whose pages serve it (get.gritpack.org by default).
Installers and download links explains
the download itself.
Careful. Links are served by
get.gritpack.orgfor every private hub that Frogfish runs. Check with Frogfish that yours is connected before you send one; a link the public hub cannot look up shows as not found.
Revoking an invitation
An invitation that has not been used can be cancelled by its ID, the
invitation= value:
$ gritpack admin invitation revoke 01a1e867-d27b-71c1-8bea-7a07c9a7b53e
revoked invitation=01a1e867-d27b-71c1-8bea-7a07c9a7b53e account=01a1e867-b1f6-7c20-a6ad-fd28f53e0615 revoked_at=1794900487
Its code then fails at login with an authentication error (exit 3), exactly like a wrong code, so the person learns nothing about why.
Looking accounts up
$ gritpack admin user list
01a1e860-95df-7c60-bbe1-5db0fd349f05 ada@example.com status=Active
01a1e865-dba3-7352-9217-40bfb4ff47cb bea@example.com status=Active
01a1e865-dc86-7153-9bdf-ef2283d4dcab cal@example.com status=Active
...
01a1e867-b1f6-7c20-a6ad-fd28f53e0615 sam@example.com status=Active
$ gritpack admin user view sam@example.com
01a1e867-b1f6-7c20-a6ad-fd28f53e0615 sam@example.com status=Active
credential=01a1e867-d172-7a70-b11c-66473aaa9678 status=Active expires_at=1797492480
view takes the email or the account ID and lists the account's
credentials: one per login, with when it expires. list shows up to 100
accounts per page (--limit); when there are more, it prints a
next_cursor= line, and --cursor with that value gets the next page. Both
take --json; the email field there is called canonical_email.
Suspending and reactivating
Suspension stops an account at once, without deleting anything. Every credential it has stops working on the next request:
$ gritpack admin user suspend sam@example.com --yes
account=01a1e867-b1f6-7c20-a6ad-fd28f53e0615 email=sam@example.com status=Suspended
From Sam's side, every command that talks to the hub now fails with an authorization error (exit 4):
$ gritpack search textkit
the hub answered HTTP 403: credential is not authorized
Reactivation undoes it, and the same credentials work again:
$ gritpack admin user reactivate sam@example.com
account=01a1e867-b1f6-7c20-a6ad-fd28f53e0615 email=sam@example.com status=Active
Suspend first when you are not sure: when someone leaves, while a lost laptop is found, or while you look into something odd.
Deleting
Careful. Deleting an account cannot be undone.
Deletion leaves a tombstone: the account's history and the packages it published stay, its credentials are revoked, and the account can never log in again. The hub refuses to delete an account that still owns a scope, so you first decide who should own its names:
$ gritpack admin user delete sam@example.com --yes
the hub answered HTTP 400: invalid administration operation
$ gritpack admin scope unassign samco --yes
unassigned @samco
$ gritpack admin user delete sam@example.com --yes
account=01a1e867-b1f6-7c20-a6ad-fd28f53e0615 email=sam@example.com status=Tombstoned
The first refusal is the scope rule. Its wording does not say so in 1.2.63;
check admin scope list for the account's scopes when you see it.
suspend, delete, scope unassign and package quarantine ask for
confirmation on a terminal. With no terminal they go ahead after a warning
today, and will need --yes from 1.4.0, so always pass --yes in scripts.
Scopes
A scope is a family of names, @team/..., that only its owner may publish
in. (Unscoped names belong to whoever publishes them first.) People can claim
a scope nobody owns with gritpack scope claim; see
Names, scopes and owners. An administrator
can give any scope to any account, whether or not someone asked:
$ gritpack admin scope assign samco --owner sam@example.com
assigned @samco owner=01a1e867-b1f6-7c20-a6ad-fd28f53e0615
$ gritpack admin scope view samco
@samco owner=01a1e867-b1f6-7c20-a6ad-fd28f53e0615
$ gritpack admin scope list
@ada owner=01a1e860-95df-7c60-bbe1-5db0fd349f05
...
@samco owner=01a1e867-b1f6-7c20-a6ad-fd28f53e0615
Write the scope without its @ in these commands. In 1.2.63 admin scope view @samco is refused with "invalid administration operation".
A common pattern is to give the team's scope (@yourcompany) to a dedicated
release account used by CI, and let people publish their experiments under
scopes of their own. A scope has one owner; several people publish to it by
sharing the work through that account in CI, or through
workspaces released together.
scope unassign takes a scope away. It does not remove any package already
published under it; the versions stay, and anyone who depends on them keeps
working. It only means nobody may publish new versions there until the scope
is assigned again.
What a scope does not do
A scope controls who may publish a name. It does not control who may see it. Every account that can log in to your hub can search for and install every package on it. If something must be hidden from some of your own people, it belongs on a different hub.
What the hub records
Every administrative change is written to the hub's audit log with the administrator certificate that made it and the state before and after. The next chapter shows how to read it, along with licence rules, quarantine and signing keys.
What just happened
You saved your administrator connection as a profile, added accounts and invited people with a code or a link, cancelled an invitation, suspended and reactivated an account, deleted one after handing over its scope, and gave scopes to accounts. None of this needed access to the hub's machine: the administrator certificate is all an administrator holds.
You can stop here
If you manage the people and names on your team's hub, you have the everyday tasks.
Next
Go on to Licence rules, quarantine and the audit log. For what the people you invite see, read Logging in.