Mario Fetka
5897512fd9
Complete the current IMAP, POP3, SMTP and proxy protocol work; add the validated setup and administration UI, packaging examples, tests, and maintained roadmap/documentation for the 0.7 development line.
137 lines
4.2 KiB
Groff
137 lines
4.2 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 ]
|
|
.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)
|