.TH BONGO-ADMIN 1 "July 2026" "Bongo 0.7.0" "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 | 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 ]
.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
The Bongo 0.7 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 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 0.7 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 the local Web and LDAP settings.  Boolean values can be
toggled and scalar, list and object values can be edited as their JSON
representation.
.TP
.B config check
Load the live configuration 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.
.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)