.TH BONGO-ADMIN 1 "July 2026" "Bongo @BONGO_V_STR@" "Bongo administration"
.SH NAME
bongo-admin \- administer local Bongo accounts, agents and authentication caches
.SH SYNOPSIS
.B bongo-admin
.B user
.BR add | info | list | password | quota | rename
.RI [ arguments ]
.br
.B bongo-admin
.B ldap-cache
.BR status | extend-all
.RI [ hours ]
.br
.B bongo-admin
.B agent
.BR list | info
.RI [ name ]
.br
.B bongo-admin
.B server
.BR list | info
.br
.B bongo-admin
.B config
.RI [ edit | check | sync ]
.br
.B bongo-admin migrate
.SH DESCRIPTION
.B bongo-admin
performs privileged administration of the local Bongo server.  It must be
run as root.  Commands which change credentials or account names are written
to the authentication log.
.PP
This command intentionally does not accept a password on the command
line.  Passwords are read without echo from the controlling terminal so they
do not appear in shell history or the process list.
.SH USER COMMANDS
.TP
.BI "user add " USER
Create a local account without an initial password.  Set its password with
.B user password
before allowing password authentication.
.TP
.BI "user info " USER
Show the canonical account name and mailbox path.  If
.I USER
is a retained login alias, show that fact as well.
.TP
.B user list
List local Bongo accounts.
.TP
.BI "user password " USER
Read and confirm a new password from the terminal.  New passwords require at
least twelve characters and are stored using the configured Argon2 password
hash.
.TP
.BI "user quota " USER " [" SIZE "|unlimited]"
Show the user's logical mail-storage usage and administrative limit.  With a
size argument, set the limit.  A size is an exact byte count or uses a binary
K, M, G, T or P suffix, optionally followed by iB or B.  The value
.B unlimited
removes the limit.  Quotas cover mail in every mailbox of the account but not
contacts, calendars, configuration data or the Queue.
.TP
.BI "user rename " OLD_NAME " " NEW_NAME
Atomically rename an account.  Active sessions are disconnected, mailbox and
per-user databases are moved, and the old name remains a login and delivery
alias.  Clients using the old name are reported as user tasks so they can be
reconfigured.
.SH LDAP OFFLINE CACHE COMMANDS
.TP
.B ldap-cache status
List cached LDAP credentials, their last verification time, expiry time and
current state.
.TP
.BI "ldap-cache extend-all [" HOURS "]"
Atomically extend all existing LDAP offline credential caches.  The default is
48 hours.  One invocation is limited to 744 hours.  This is an emergency
operation for a known directory outage, not a replacement for restoring LDAP.
.SH AGENT AND SERVER COMMANDS
.TP
.B agent list
Read the live manager configuration from the Store and list configured agents,
their enabled state and startup priority.
.TP
.BI "agent info " NAME
Show the manager configuration for one agent.
.TP
.BR "server list" , " server info"
Show the local server hostname, Bongo version, state directory and manager
status.  Bongo has one local managed server, so both forms report the same
server.
.SH CONFIGURATION COMMANDS
.TP
.BR config , " config edit"
Open the curses configuration editor.  The editor covers Store protocol
documents as well as Web and LDAP settings.  It reads the operative Store and
commits validated changes to the Store and
.I /etc/bongo/config.d
together.
.TP
.B config check
Load the suffixless local configuration files and run type, range, path,
listener collision,
trusted-proxy, relay, LDAP, scanner, DKIM and SRS plausibility checks without
opening curses.  Errors produce a non-zero status; warnings do not.
.TP
.B config sync
Validate the files below
.I /etc/bongo/config.d
and
.I /etc/bongo/aliases.d,
then ask the running manager to synchronize them into the Store.  Agents read
only the Store; direct file edits are therefore not active until this command
or the next manager start.
.TP
.B migrate
Perform the explicit one-time import of pre-0.7 Store and local configuration.
Consumed historical files are moved below
.IR /etc/bongo/migration-backup/pre-0.7 .
If both historical TLS files exist, they are moved to
.I /etc/bongo/ssl.d/server.crt
and
.IR /etc/bongo/ssl.d/server.key ;
an incomplete pair is rejected.
They are never used as runtime fallbacks.
.PP
A save validates all documents together, serializes concurrent changes,
atomically replaces local files and restores earlier writes when a later
document fails.  Listener changes take effect after the affected Bongo agents
are restarted.
.SH COMPATIBILITY COMMANDS
The historical aliases
.BR user-add ,
.BR user-info ,
.BR user-list ,
.BR user-passwd ,
.BR agent-list ,
.BR agent-info ,
.BR server-list
and
.BR server-info
are accepted, including their two-letter aliases.
.PP
The former MDB commands
.BR import ,
.BR setup-genschema ,
.BR setup-mdb ,
.BR setup-rights ,
.BR agent-delete ,
.BR agent-modify ,
.BR user-delete
and arbitrary
.B user-modify
were tied to the removed MDB directory and are not emulated.  Initial setup,
certificate generation and basic account creation are provided by
.BR bongo-config (1).
.SH SECURITY
Do not pass secrets as command arguments or redirect them from a shared file.
Use service-scoped app passwords for IMAP, POP3, SMTP and ManageSieve when
two-factor authentication is enabled.  Renames and LDAP cache extensions
should be reviewed in the authentication log.
.SH SEE ALSO
.BR bongo-config (1),
.BR bongo-setup (1),
.BR bongo-manager (1),
.BR bongoagents (8)