@ -44,33 +44,92 @@ In case you need to re-authenticate an existing group, do the same but use `-A`
### Editing config
**Do not edit the config while the group service is running, it may overwrite your changes!**
**JSON does not support comments! Remove comments before using examples copied from this guide!**
Each group is stored as a sub-directory in `groups.d`. The sub-directories are normally named after their accounts,
but this is not required.
A typical setup could look like this:
The group's config and state is split into three files:
```
├── groups.d
│ ├── betty@piggo.space
│ │ ├── config.json
│ │ ├── control.json
│ │ └── state.json
│ └── chatterbox@botsin.space
│ ├── config.json
│ ├── control.json
│ └── state.json
└── groups.json
```
#### Common config
There is one shared config file: `groups.json`
- `config.json` - immutable config, never changed beside when you run the -A command to reauth the group.
This is where the auth token and the `enabled` flag are stored.
- `control.json` - settings and state that changes at runtime or can be set using slash commands.
- If the file does not exist, default settings are used. This is usually good enough.
- This file applies to all groups
- Prior to 0.3, the groups were also configured here.
- Running 0.3+ with the old file will produce an error, you need to update the config before continuing - move groups to subfolders
```
{
// Max number of missed notifs to process after connect
max_catchup_notifs: 30,
// Max number of missed statuses to process after connect
max_catchup_statuses: 50,
// Delay between fetched pages when catching up
delay_fetch_page_s: 0.25,
// Delay after sending a status, making a follow or some other action.
// Set if there are Throttled errors and you need to slow the service down.
delay_after_post_s: 0.0,
// Delay before trying to re-connect after the server closed the socket
delay_reopen_closed_s: 0.5,
// Delay before trying to re-connect after an error
delay_reopen_error_s: 5.0,
// Timeout for a notification/timeline socket to be considered alive.
// If nothing arrives in this interval, reopen it. Some servers have a buggy socket
// implementation where it stays open but no longer works.
socket_alive_timeout_s: 30.0,
// Time after which a socket is always closed, even if seemingly alive.
// This is a work-around for servers that stop sending notifs after a while.
socket_retire_time_s: 120.0,
}
```
#### Per-group config
Each group is stored as a sub-directory of `groups.d/`. The sub-directories are normally named after their accounts,
but this is not required. For example, `groups.d/betty@piggo.space/`.
The group's config and state is split into three files in a way that minimizes the risk of data loss.
Only the `config.json` file with credentials is required; the others will be created as needed by the group daemon.
- `config.json` - immutable config, never changed beside when you run the `-A` command to reauth a group.
This is where the account name, the auth token and the `enabled` flag are stored.
- `control.json` - settings and state that change at runtime or can be set using slash commands.
This file is overwritten by the group service when needed.
- `state.json` - frequently changing state data. The last-seen status/notification timestamps are kept here.
State is split from Control to reduce the risk of damaging the control file. Timestamps can be updated multiple times
State is split from Control to limit the write frequency of the control file. Timestamps can be updated multiple times
per minute.
**Do not edit the control and state files while the group service is running, it may overwrite your changes!**
The JSON files are easily editable, you can e.g. add yourself as an admin (use the e-mail format, e.g. `piggo@piggo.space`).
Note that changing config externally requires a restart. It's better to use slash commands and update the config at run-time.
When adding hashtags, note that *they must be entered as lowercase*!
When adding hashtags, *they must be entered as lowercase* and without the `#` symbol!
The file format is quite self-explanatory.
The file formats are quite self-explanatory (again, remove comments before copying, JSON does not support comments!)
#### config.json
**config.json**
```json
{
// Enable or disable the group service
"enabled": true,
// Group account name
"acct": "group@myserver.xyz",
// Saved mastodon API credentials
"appdata": {
"base": "https://myserver.xyz",
"client_id": "...",
@ -81,31 +140,35 @@ The file format is quite self-explanatory.
}
```
#### control.json
**control.json**
```json
{
// List of group hashtags, lowercase.
// The group reblogs anything with these hashtags if the author is a member.
"group_tags": [
"grouptest"
],
// List of admin users (e-mail format)
"admin_users": [
"admin@myserver.xyz"
],
// Restrict write access to manually added members
"member_only": false,
// List of member users (e-mail format)
"member_users": [],
// List of banned users (e-mail format), their posts and actions are ignored by the group
"banned_users": [],
// List of banned servers, users from there can't interact with the group and their posts can't be shared.
"banned_servers": [
"bad-stuff-here.cc"
]
}
```
- `group_tags` - group hashtags (without the `#`), lowercase! The group reblogs anything with these hashtags if the author is a member.
- `member_users` - group members, used to track whose hashtags should be reblogged; in member-only groups, this is also a user whitelist.
- `banned_users` - can't post or interact with the group service
- `banned_servers` - work like an instance block
**state.json**
#### state.json
Internal use, millisecond timestamps of the last-seen status and notification.
```json
{
@ -116,12 +179,15 @@ The file format is quite self-explanatory.
### Running
To run the group service, simply run it with no arguments. It will find groups in `groups.d` and start the service threads for you.
To run the group service, simply run it with no arguments.
It will read the `groups.json` file (if present), find groups in `groups.d/` and start the services for you.
Note that the control and status files must be writable, they are updated at run-time. Config files can have restricted permissions
to avoid accidental overwrite.
Note that the control and status files must be writable, they are updated at run-time.
Config files can have limited permissions to avoid accidental overwrite.
An example systemd service file is included in the repository as well. Make sure to set up the system user/group and file permissions according to your needs. You can use targets in the included `Makefile` to manage the systemd service and look at logs.
An example systemd service file is included in the repository as well.
Make sure to set up the system user/group and file permissions according to your needs.
You can use targets in the included `Makefile` to manage the systemd service and look at logs.
## Group usage
@ -145,7 +211,6 @@ These won't be shared:
- `ducks suck`
- `@group #ducks /i` (anything with the "ignore" command is ignored)
- `@group /remove #ducks` (admin command, even if it includes a group hashtag)
- `@otheruser tell me about #ducks` (in a thread)
- `@otheruser @group tell me about ducks` (in a thread)
