From e53c7584712707e877acf6c1d66061f998aa66aa Mon Sep 17 00:00:00 2001 From: James Lu Date: Sun, 25 Dec 2016 00:41:41 -0800 Subject: [PATCH] docs: reorganize & include a list of all PyLink permissions Closes #365. --- docs/README.md | 7 +++ docs/automode.md | 26 +--------- docs/permissions-reference.md | 91 +++++++++++++++++++++++++++++++++++ docs/relay-permissions.md | 17 ------- example-permissions.yml | 7 +-- 5 files changed, 104 insertions(+), 44 deletions(-) create mode 100644 docs/permissions-reference.md delete mode 100644 docs/relay-permissions.md diff --git a/docs/README.md b/docs/README.md index 4fea0c9..a8a7dab 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,8 +6,15 @@ This folder contains general documentation for PyLink IRC services. - [PyLink FAQ (Frequently Asked Questions)](faq.md) - [PyLink Relay Tutorial & Oper Guide](pylink-opers.md) + +---- + - [Automode & Exttargets Guide](automode.md) - [Advanced Relay Configuration](advanced-relay-config.md) +- [PyLink Permissions Reference](permissions-reference.md) + +---- + - [Developer documentation](technical/) There is also a Doxygen-powered API reference at https://pylink.github.io/ diff --git a/docs/automode.md b/docs/automode.md index 46a8ae0..ac3bf11 100644 --- a/docs/automode.md +++ b/docs/automode.md @@ -45,30 +45,8 @@ Extended targets or exttargets *replace* regular hostmasks with conditional matc ## Permissions -Automode defines the following permissions, which can be customized by defining the `permissions:` configuration block (see [example-permissions.yml](../example-permissions.yml) for examples). - -By default, Automode integrates with Relay by only allowing access lists to be created on the network that owns each channel. - -- `automode.manage` OR `automode.manage.*`: ability to manage Automode (use `setacc` and `delacc`) on all channels on the network where the user is connected. -- `automode.manage.relay_owned`: ability to manage Automode on channels owned by the current network in Relay. If Relay isn't loaded or the channel in question isn't shared via Relay, this permission check FAILS. **With the default permissions set, this is granted to all opers.** -- `automode.manage.#channel`: ability to manage Automode on the specific given channel. - -- `automode.list` OR `automode.list.*`: ability to list Automode on all channels. **With the default permissions set, this is granted to all opers.** -- `automode.list.relay_owned`: ability to list automode on channels owned via Relay. If Relay isn't loaded or the channel in question isn't shared via Relay, this permission check FAILS. -- `automode.list.#channel`: ability to list Automode access entries on the specific given channel. - -- `automode.sync` OR `automode.sync.*`: ability to sync automode on all channels. -- `automode.sync.relay_owned`: ability to sync automode on channels owned via Relay. If Relay isn't loaded or the channel in question isn't shared via Relay, this permission check FAILS. **With the default permissions set, this is granted to all opers.** -- `automode.sync.#channel`: ability to sync automode on the specific given channel. - -- `automode.clear` OR `automode.clear.*`: ability to clear automode on all channels. -- `automode.clear.relay_owned`: ability to clear automode on channels owned via Relay. If Relay isn't loaded or the channel in question isn't shared via Relay, this permission check FAILS. -- `automode.clear.#channel`: ability to clear automode on the specific given channel. - -- `automode.savedb`: ability to save the automode DB. - -Remote versions of the `manage`, `list`, `sync`, and `clear` commands also exist for cross-network manipulation (e.g. `automode.remotemanage.*`) +See the [Permissions Reference](permissions-reference.md#automode) for a list of permissions defined by Automode. ## Caveats -- Service bot joining and Relay don't always behave consistently: https://github.com/GLolol/PyLink/issues/265 +- Service bot joining and Relay don't always behave consistently: see https://github.com/GLolol/PyLink/issues/265 diff --git a/docs/permissions-reference.md b/docs/permissions-reference.md new file mode 100644 index 0000000..78eb755 --- /dev/null +++ b/docs/permissions-reference.md @@ -0,0 +1,91 @@ +# PyLink Permissions Reference + +Below is a list of all the permissions defined by PyLink and its official plugins. For instructions on how to fine-tune permissions, see [example-permissions.yml](../example-permissions.yml). + +## PyLink Core +- `core.shutdown` - Allows access to the `shutdown` command. +- `core.load` - Allows access to the `load` command. +- `core.unload` - Allows access to the `unload` command. +- `core.reload` - Allows access to the `reload`, `load`, and `unload` commands. (This implies access to `load` and `unload` because `reload` is really just those two commands combined.) +- `core.rehash` - Allows access to the `rehash` command. + +## Automode + +By default, Automode integrates with Relay by only allowing access lists to be created / manipulated on channels that are owned by a network via Relay. + +- `automode.manage` OR `automode.manage.*`: ability to manage Automode (use `setacc` and `delacc`) on all channels on the network where the user is connected. +- `automode.manage.relay_owned`: ability to manage Automode on channels owned by the current network in Relay. If Relay isn't loaded or the channel in question isn't shared via Relay, this permission check FAILS. **With the default permissions set, this is granted to all opers.** +- `automode.manage.#channel`: ability to manage Automode on the specific given channel. + +- `automode.list` OR `automode.list.*`: ability to list Automode on all channels. **With the default permissions set, this is granted to all opers.** +- `automode.list.relay_owned`: ability to list automode on channels owned via Relay. If Relay isn't loaded or the channel in question isn't shared via Relay, this permission check FAILS. +- `automode.list.#channel`: ability to list Automode access entries on the specific given channel. + +- `automode.sync` OR `automode.sync.*`: ability to sync automode on all channels. +- `automode.sync.relay_owned`: ability to sync automode on channels owned via Relay. If Relay isn't loaded or the channel in question isn't shared via Relay, this permission check FAILS. **With the default permissions set, this is granted to all opers.** +- `automode.sync.#channel`: ability to sync automode on the specific given channel. + +- `automode.clear` OR `automode.clear.*`: ability to clear automode on all channels. +- `automode.clear.relay_owned`: ability to clear automode on channels owned via Relay. If Relay isn't loaded or the channel in question isn't shared via Relay, this permission check FAILS. +- `automode.clear.#channel`: ability to clear automode on the specific given channel. + +- `automode.savedb`: ability to save the automode DB. + +Remote versions of the `manage`, `list`, `sync`, and `clear` commands also exist for cross-network manipulation (e.g. `automode.remotemanage.*`) + +## Bots + +- `bots.spawnclient` - Allows access to the `spawnclient` command. +- `bots.quit` - Allows access to the `quit` command. +- `bots.joinclient` - Allows access to the `joinclient` command. +- `bots.nick` - Allows access to the `nick` command. +- `bots.part` - Allows access to the `part` command. +- `bots.msg` - Allows access to the `msg` command. + +## Changehost + +- `changehost.applyhosts` - Allows access to the `applyhosts` command. + +## Commands +- `commands.status` - Allows access to the `status` command. **With the default permissions set, this is granted to all users.** +- `commands.showuser` - Allows access to the `showuser` command. **With the default permissions set, this is granted to all users.** +- `commands.showchan` - Allows access to the `showchan` command. **With the default permissions set, this is granted to all users.** +- `commands.echo` - Allows access to the `echo` command. +- `commands.logout.force` - Allows forcing logouts on other users via the `logout` command. +- `commands.loglevel` - Allows access to the `loglevel` command. + +## Exec +- `exec.exec` - Allows access to the `exec` command. +- `exec.eval` - Allows access to the `eval` command. +- `exec.raw` - Allows access to the `raw` command. +- `exec.inject` - Allows access to the `inject` command. + +## Networks +- `networks.disconnect` - Allows access to the `disconnect` command. +- `networks.autoconnect` - Allows access to the `autoconnect` command. +- `networks.remote` - Allows access to the `remote` command. +- `networks.reloadproto` - Allows access to the `reloadproto` command. + +## Opercmds +- `opercmds.checkban` - Allows access to the `checkban` command. +- `opercmds.jupe` - Allows access to the `jupe` command. +- `opercmds.kick` - Allows access to the `kick` command. +- `opercmds.kill` - Allows access to the `kill` command. +- `opercmds.mode` - Allows access to the `mode` command. +- `opercmds.topic` - Allows access to the `topic` command. + +## Relay +- `relay.claim` - Allows access to the `claim` command. +- `relay.create` - Allows access to the `create` command. **With the default permissions set, this is granted to all opers.** +- `relay.delink` - Allows access to the `delink` command. **With the default permissions set, this is granted to all opers.** +- `relay.destroy` - Allows access to the `destroy` command. **With the default permissions set, this is granted to all opers.** +- `relay.destroy.remote` - Allows access to the `remote` command. +- `relay.linkacl` - Allows access to the `linkacl` command. **With the default permissions set, this is granted to all opers.** +- `relay.linkacl.view` - Allows access to the `view` command. **With the default permissions set, this is granted to all opers.** +- `relay.link` - Allows access to the `link` command. **With the default permissions set, this is granted to all opers.** +- `relay.linked` - Allows access to the `link` command. **With the default permissions set, this is granted to all users.** +- `relay.purge` - Allows access to the `purge` command. +- `relay.savedb` - Allows access to the `savedb` command. + +## Servermaps +- `servermaps.map` - Allows access to the `map` and `localmap` commands. diff --git a/docs/relay-permissions.md b/docs/relay-permissions.md deleted file mode 100644 index 0fb04af..0000000 --- a/docs/relay-permissions.md +++ /dev/null @@ -1,17 +0,0 @@ -## Relay Permissions - -Relay defines the following permissions, which can be customized by defining the `permissions:` configuration block (see [example-permissions.yml](../example-permissions.yml) for examples). - -By default, the following permissions are given to opers: - -- `relay.create` -- `relay.destroy` -- `relay.claim` -- `relay.link` -- `relay.delink` -- `relay.linkacl.view` -- `relay.linkacl` - -The following permissions are given to all users: - -- `relay.linked` diff --git a/example-permissions.yml b/example-permissions.yml index b8575e4..35a5bd2 100644 --- a/example-permissions.yml +++ b/example-permissions.yml @@ -1,6 +1,7 @@ -# This file is an example of the permissions system in PyLink. Should you wish, -# you may copy the contents of this file and paste it into the configuration you're -# using. +# This file is an example of the permissions system in PyLink. To fine-tune permissions, you should +# merge the "permissions:" block in this file with the one in your PyLink configuration, creating it +# if it doesn't already exist. Simply renaming this file to permissions.yml DOES NOT work! + # Permissions work by mapping hostmasks, accounts, and exttargets to lists of permissions, allowing # you to fine tune which users have access to which commands.