Skip to main content

Settings for administrators

Where BeeBEEP keeps its files, the administrator's policy file, and the keys of beebeep.ini an administrator may set, with values and defaults.

For: administrators · From BeeBEEP 6.0.0 · Updated on

BeeBEEP keeps each installation's settings in one plain text file, beebeep.ini, and reads a machine-wide policy from a second file, beebeep.rc, that only an administrator can write. This page says where both are, which folder holds a user's data, and what every key an administrator may set does, with its values and its default.

The data folder

A user's own data lives in one folder: the settings (beebeep.ini), the encrypted database (beebeep.db), the daily logs and, when you use one, beehosts.ini. BeeBEEP chooses the folder by the first of these that applies:

  1. The policy file. DataFolder/Path in beebeep.rc (see the policy file). It wins over everything below, --data-folder included.
  2. The command line. --data-folder=<path>, for that run.
  3. Portable mode. If the folder that holds the BeeBEEP executable is writable, BeeBEEP uses a folder named beebeep-data inside it, so a copy on a USB stick carries its data. This never applies on macOS, Android or iOS, and on Windows never under Program Files.
  4. The system's default folder for the application configuration, under MarcoMastroddiSW/BeeBEEP.

In the policy file and on the command line the path may contain the word {account}, replaced by the name of the operating system account. Point it at a shared location and every account gets a folder of its own there:

[DataFolder]
Path=D:/BeeBEEP/{account}

Only letters, digits, -, _, . and spaces of the account name are kept. A path longer than 240 characters, or an {account} on a system that gives no account name, stops BeeBEEP at start with an error; it never falls back to another folder.

Every daily log is beebeep-<year>-<month>-<day>.log in the data folder, and BeeBEEP deletes the ones older than 7 days.

Windows

The default data folder is %LOCALAPPDATA%\MarcoMastroddiSW\BeeBEEP, one per account, so the settings are %LOCALAPPDATA%\MarcoMastroddiSW\BeeBEEP\beebeep.ini. Uninstalling BeeBEEP leaves it in place (installing on Windows).

Linux

The default data folder is ~/.config/MarcoMastroddiSW/BeeBEEP, so the settings are ~/.config/MarcoMastroddiSW/BeeBEEP/beebeep.ini. The headless node beebeep-relay uses BeeBEEP-Relay in place of BeeBEEP, so it never shares a folder, or a database, with the desktop program of the same account.

The policy file

beebeep.rc is the administrator's file. BeeBEEP reads it from one fixed place, never from the folder of the executable or from the user's own folder, so that only an account that can write there can set a policy.

SystemPlace
Windows%ProgramData%\BeeBEEP\beebeep.rc
macOS/Library/Application Support/BeeBEEP/beebeep.rc
Linux/etc/beebeep/beebeep.rc

The file is an INI file. When it does not exist, no policy applies. It holds the data folder above, the plugin switches, the hosts keys, the circles and the windows for changing a message below. A beehosts.ini in the same folder is read even when beebeep.rc does not exist (see the beehosts.ini file). On a computer, File > Open resource folder opens this folder once it exists; while it does not, it opens the folder BeeBEEP is installed in.

Plugin switches

These five keys are read from beebeep.rc only, never from beebeep.ini and never from the command line, so a user cannot flip an administrator's choice. A boolean is written true or false, yes or no, on or off, 1 or 0, in any case; another word leaves the default and writes a warning to the log.

[Plugins]
Enabled=true
DisabledCategories=game
AllowScreenCapture=true
AllowUnsigned=false
AllowExternal=false
DataFolderFirst=false
KeyValuesDefaultWhat it does
Enabledbooleantruefalse loads no plugin at all: no plugin folder is scanned and every plugin invitation received is answered as unavailable, with nothing shown to the user
DisabledCategoriesgame, utility, communication, comma separatednonea plugin of a listed category is never loaded, and an invitation to one is answered as unavailable, with nothing shown; an unknown word is ignored with a warning in the log
AllowScreenCapturebooleantruefalse removes every way of using a plugin that captures the screen, such as sharing it: it is never offered, and an invitation to it is answered as unavailable; the plugin's other uses stay, and a plugin with no other use is not loaded
AllowUnsignedbooleanfalsetrue loads a plugin library that has no valid signature; for development only
AllowExternalbooleanfalsetrue registers external plugins, programs that BeeBEEP starts and talks to; off, BeeBEEP starts no program
DataFolderFirstbooleanfalsetrue prefers a plugin in the user's data folder over the copy installed with BeeBEEP, for trying a new build of a plugin; a plugin still needs a valid signature; for development only

Turning voice calls off

Voice calls come with BeeBEEP as the Call plugin, of the communication category. To turn them off on a computer, list that category in its beebeep.rc:

[Plugins]
DisabledCategories=communication

The Call plugin is then not loaded: the phone button does not appear in any chat, and a call to this computer is answered as unavailable, with nothing shown to its user; the caller reads that this person does not have Call. To turn off calls and games together, list both: DisabledCategories=communication, game. Enabled=false turns off every plugin, calls included.

Keeping BeeBEEP to a list of computers

Three more keys of beebeep.rc, read from it only, decide how BeeBEEP uses beehosts.ini (see the beehosts.ini file). Their list is the administrator's copy of beehosts.ini, the one in the same folder as beebeep.rc, never the user's. Booleans are written as for the plugin switches.

[HostsFile]
IgnoreUserFile=true
AcceptOnlyFromListed=true
AnnounceOnlyToListed=true
KeyValuesDefaultWhat it does
IgnoreUserFilebooleanfalsetrue reads only the administrator's beehosts.ini; the one in the user's data folder is ignored
AcceptOnlyFromListedbooleanfalsetrue connects only with the computers the administrator's file lists, in both directions; an announcement from another address is ignored, and a user who adds another address by hand is told that the administrator does not allow it
AnnounceOnlyToListedbooleanfalsetrue sends nothing by broadcast or multicast (and does not publish BeeBEEP with Bonjour); BeeBEEP announces itself only to the computers and networks the administrator's file lists

A computer is listed by its address (any port), by a network line that holds its address, or by a host name, at the address the name has when BeeBEEP looks it up: at start, and whenever its own network changes. Until the first lookup of a name has answered, that name lists nothing.

The keys apply to direct network connections only. A user reached through another BeeBEEP that relays for both, or over Bluetooth, is not a connection this computer makes, and stays reachable.

Keeping a search inside your own network

When the user searches farther than the nearest addresses (the Medium and Far distances), BeeBEEP also announces itself to the networks next to its own -- the blocks of 256 addresses around it, inside the private range that holds its address, never a public one -- so that an office split over two networks finds itself. One key of beebeep.rc keeps every search inside the computer's own network:

[Network]
SearchBeyondOwnNetwork=false
KeyValuesDefaultWhat it does
SearchBeyondOwnNetworkbooleantruefalse keeps the Medium and Far searches inside the computer's own network: they cover more of it when it is larger than 256 addresses, never the networks next to it

AnnounceOnlyToListed above still applies to every search.

Circles

A circle is a name, and people who share one see each other (circles says what a user sees). The simplest way to set up an office is to give every computer its circles in beebeep.rc, so that the user does nothing. The key is read from beebeep.rc when BeeBEEP starts.

[Circles]
Names=Doctors, Doctor A
KeyValuesDefaultWhat it does
Namescircle names, separated by commasnot setsets the circles of this installation and locks them: the list is shown in Settings > Privacy with Set by your administrator., and the user cannot add or remove one; Names= with nothing after it is no circles, locked; with no Names in the file the list is the user's own

A list set here is applied over the user's own, which stays in beebeep.ini untouched and comes back the day the file stops setting it. A name that the rules refuse is left out and a warning is written to the log: BeeBEEP never refuses to start for it. The rules are those a user meets: at most 32 characters, at least one letter or digit, no emoji, a name once per circle however it is written in capitals or with extra spaces, and the whole list within 320 bytes, two for each name counted besides its text (a comma separates names, so a name never holds one). A name longer than 32 characters is shortened to its first 28, then # and three letters or digits taken from the whole name, so the same long name gives the same short one on every computer, and files that list different long names agree on each; the warning in the log gives the short form.

Two keys of beebeep.ini belong to circles too, both written by BeeBEEP:

KeyValuesDefaultWhat it does
Circles/Namescircle names, separated by commasnonethe user's own circles, chosen in Settings > Privacy; not used while beebeep.rc sets Names
Circles/GroupUsersByCirclebooleanfalsegroups the list of users by circle, as Group people by circle in the sort menu of Users does; kept when the last circle goes

The headless relay node beebeep-relay has no circles: it ignores [Circles] in both files, passes messages for everybody and is in sight of everyone.

Editing and deleting a sent message

A user can correct a message they sent, or delete it for everyone: every copy then shows "This message was deleted" in its place. They can do it for a while after writing it; these keys set how long. An office that keeps its chats as a record turns both off. A key set here applies over anything the user's own file says, and cannot be changed while BeeBEEP runs.

[Messages]
messageEditWindowSecs=0
messageDeleteWindowSecs=0
KeyValuesDefaultWhat it does
messageEditWindowSecsseconds, 0 or more900how long after writing a message its sender may still edit it (15 minutes); 0 turns editing off
messageDeleteWindowSecsseconds, 0 or more86400how long after writing a message its sender may still delete it for everyone (a day); 0 turns deleting for everyone off

While nobody has received a message yet, its sender can always delete it, and correct it, with no time limit. Deleting a message only for oneself is never limited. The time is counted from when the message was written, on the sender's computer; a computer with another value does not refuse a change sent from one with a longer time.

Editing beebeep.ini

beebeep.ini is a plain INI file: each key belongs to a [Group], and this page names a key as Group/Key. A boolean is true or false.

[Network]
PreferIPv6=true

[FileTransfer]
AutoAcceptMaxSizeMiB=50

A day of use is a day on which BeeBEEP ran on that computer; days when it was switched off do not count.

Where the secrets are kept

BeeBEEP holds three secrets: the password that encrypts the database, the private key of your end-to-end identity, and the network password. Where they are kept depends on the machine.

With a secret store on the system, the three go there, under the service name BeeBEEP, and never into beebeep.ini: the Keychain on macOS and iOS, and through the qtkeychain library the Credential Manager on Windows, the Secret Service or KWallet on Linux, and the Keystore on Android.

A machine that has no secret store at all, such as a server with no desktop session, is detected when BeeBEEP starts: it asks the store once, and only an answer that says no store exists counts. A store that is locked, or a prompt that is declined, does not: BeeBEEP keeps using the store and does not fall back. When no store exists, BeeBEEP keeps the three secrets in plain text in beebeep.ini itself, next to the settings.

--secret-file=<path> is for that machine. The file holds a master secret, with any content you choose; a trailing newline is ignored, and a secret shorter than 16 bytes is accepted with a warning. BeeBEEP then keeps the three secrets in an encrypted file, beebeep.secrets, in the data folder, unlocked by the master secret, and never touches the system's secret store, even where one exists. BeeBEEP only reads the master secret file: keep it outside the data folder, readable by the account that runs BeeBEEP alone, or hand it over through your service manager. If beebeep.secrets does not decrypt with that secret, or cannot be read, BeeBEEP stops at start with an error and does not touch the database.

Network

KeyValuesDefaultWhat it does
Network/UseNetworkPasswordbooleanfalseapplies the saved network password to new connections; turning it off keeps the saved password
Network/UseBonjourbooleantrue on macOS, iOS and Android, false elsewherepublishes this installation and looks for others over Bonjour; applied at once, without a restart
Network/PreferIPv6booleanfalsereaches a user offered on both IPv4 and IPv6 over IPv6; a user offered on one family is reached over that one
Network/ListenPorta port, 1 to 655356475the TCP port BeeBEEP asks for when it starts; BeeBEEP stores the port it ended up listening on and asks for that one the next time; --listen-port overrides it for one run
Network/EffortLevelNormal, High, Max (or 0, 1, 2)Normalhow much traffic this installation spends on keeping its connections alive: at most 25 packets a second for Normal, 60 for High, 240 for Max
Network/LegacyBridgeEnabledbooleantruetalks to users running BeeBEEP 5.x; see the note below the table

With Network/LegacyBridgeEnabled on, BeeBEEP talks to BeeBEEP 5.x users, and it tells every user it connects to the name and domain of the operating system account, but only when this installation's identity was derived from that account. With it off, BeeBEEP does not talk to BeeBEEP 5.x users and tells nobody the account name.

The same choices are in Settings > Network: Use network password, Find peers with Bonjour, Prefer IPv6 over IPv4, Network effort and Talk to BeeBEEP 5.x peers.

Privacy and security

KeyValuesDefaultWhat it does
Privacy/ShareProfileWithEveryone, ContactsOnlyContactsOnlywho may fetch your email, phone number, location, birth date and info: any user, or only your Contacts; any other value reads as ContactsOnly
Privacy/ShareGalleryWithEveryone, ContactsOnlyContactsOnlythe same for your gallery
Privacy/DropGroupInvitationsFromNonContactsbooleanfalsediscards a group invitation from someone who is not a Contact, instead of showing it with a warning
Privacy/AcceptGroupInvitationsFromContactsbooleanfalseaccepts at once a group invitation from a Contact, without asking; an invitation from anyone else, or to a game, still waits for the user
Security/AutoAcceptKeyChangesbooleantrueaccepts by itself the new security key of a user you have not verified in person; false makes every change wait for you to confirm it in that user's chat

Files

KeyValuesDefaultWhat it does
FileTransfer/AutoAcceptMaxSizeMiBwhole number, 0 to 10485760 on a computer, 20 on Android and iOSthe largest file, in MiB, that a Contact's offer downloads without asking; 0 sets no limit; a file offered by someone who is not a Contact always waits, and a voice note always downloads
FileTransfer/OfferTtlDayswhole number7how many days of use of this installation a file you sent, and the recipient has not taken, stays on offer before the offer fails; 0 or less never expires one

The limit is also in Settings > Preferences > Download automatically.

Notifications and appearance

KeyValuesDefaultWhat it does
Notifications/Enabledbooleantrueshows notifications of the operating system
Notifications/Soundbooleantrueplays BeeBEEP's own beep with each notification, unless the system's do not disturb is on
Notifications/FlashWindowbooleantrueon a computer, flashes the window's button in the taskbar with each notification while BeeBEEP is not in front, until it is opened
Appearance/ThemeSystem, Light, DarkSystemSystem follows the light or dark setting of the operating system, the others fix one
Language/Localea locale name such as it or zh_CNemptythe language of the program; empty follows the system's languages; applied at the next start
Language/TranslationsFoldera pathemptya folder whose translation files are read before the ones built into BeeBEEP; a relative path is taken from the data folder; empty is the translations folder of the data folder
Shortcuts/Enabledbooleanfalseturns on BeeBEEP's own keyboard shortcuts; the system's usual keys always work
Shortcuts/HideToTraya key such as Ctrl+MCtrl+Mthe key that hides BeeBEEP; the settings screen accepts only a key with Ctrl, Alt or Meta
Shortcuts/PresetMessagesa key such as Ctrl+Shift+PCtrl+Shift+Pthe key of the preset messages: in a chat it opens or closes their list above the message field, elsewhere it opens them in Settings; the same rule as above
VoiceMessage/MaxDurationSecondswhole number120a voice recording stops by itself at this length; no screen sets it
Screenshot/KeepInPicturesbooleantrueon a computer, keeps a screenshot taken in a chat in the BeeBEEP folder of the user's Pictures; false writes it to a temporary folder emptied the day after. Settings > Preferences > Keep my screenshots sets it too

Housekeeping and diagnostics

KeyValuesDefaultWhat it does
Cleanup/GroupMemberDayswhole number, 0 to 365090the days of use each new group starts with for removing members not seen; 0 creates groups without that rule. Settings > Privacy sets it too
Cleanup/InactiveUserDayswhole number, 0 to 365030removes from the lists a user who is offline, has connected at least once and has not been seen for this many days of use of this installation: someone with messages, a group, a contact or a block is only hidden, and shown again when they come back; anyone else is deleted. 0 never removes anyone. Settings > Privacy sets it too
Log/PanicModebooleanfalsewrites every message of every category to the log, Qt's own included; takes effect at the next start; Settings > Log > Enable panic log and --panic-mode set it too

The beehosts.ini file

A file named beehosts.ini in the data folder is read each time BeeBEEP starts. It names the hosts to contact directly and the hosts to block, one per line. A line that starts with #, * or / is a comment.

A beehosts.ini in the same folder as beebeep.rc is the administrator's own: it is read too, first, and a user cannot change it. A block in either file wins over a host to contact in either, and the administrator's lines are the list the policy file's hosts keys use.

Hosts to contact

A line host[:port] [udp|tcp] names a computer BeeBEEP cannot find by itself, on another subnet or across a VPN: an address or a host name, with the way BeeBEEP makes the first contact. The same file can be copied to every computer it lists, since each BeeBEEP skips its own entry. The syntax, the two ways and the ports to open are in reaching computers on other networks.

office-pc.tailnet-name.ts.net
192.168.3.32
server.example.com tcp

Hosts to block

A line that starts with ! blocks a host: BeeBEEP neither connects to it nor accepts a connection from it, from the first announcement on.

!10.184.9.132
!2001:db8:1f70::999:de8:7648:6e8

A block names an address, never a host name, and covers the whole host: a port written after the address is ignored and a warning is written to the log. The --block-address=<host[:port]> option adds a block for one run, and can be repeated.

Command-line options

OptionWhat it does
--data-folder=<path>uses <path> for the settings, the database and the logs; see the data folder
--language=<locale>the language for this run, ahead of Language/Locale and the system
--secret-file=<path>keeps the database password, the identity key and the network password in an encrypted beebeep.secrets in the data folder, unlocked by the master secret in this file; see where the secrets are kept
--network-password-file=<path>uses the content of the file as the network password for this run, and never stores it
--panic-modeverbose logging, and keeps it for the next runs
--block-address=<host[:port]>blocks a host for this run; repeatable
--listen-port=<port>the TCP port to listen on for this run, ahead of Network/ListenPort
--versionprints the version and exits
--helplists every option and exits

An option that takes one value is refused, with an error at start, when it is given twice.

All the help pages