Mario Fetka
161 lines
4.9 KiB
Groff
161 lines
4.9 KiB
Groff
.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 | 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
|
|
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 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)
|