Skip to content

Latest commit

 

History

History
699 lines (506 loc) · 23.9 KB

Configuration.md

File metadata and controls

699 lines (506 loc) · 23.9 KB
Raw

The main configuration file for LuckPerms can be found at these locations.

Platform Location
Bukkit/Spigot /plugins/LuckPerms/config.yml
BungeeCord /plugins/LuckPerms/config.yml
Sponge /config/luckperms/luckperms.conf

Links to the default file for each platform are above. Please note that the configuration does not automatically update when new options are added. The default options are used if nothing is found in the file.

Index

Essential Settings

Storage Settings

Update Propagation & Messaging Service

Customization Settings

Permission Calculation & Inheritance

Permission resolution settings
Inheritance settings
Bukkit
Bungee
Sponge
Extra settings

Fine Tuning Options

Server Operator / Vault (Bukkit version only)

Miscellaneous Settings

Descriptions

server

The name of the server, used for server specific permissions.

If set to "global" this setting is ignored. More details about how server specific permissions are groups work can be found here.

Example
server: global

use-server-uuid-cache

If the servers own UUID cache/lookup facility should be used when there is no record for a player in the LuckPerms cache.

When this setting is disabled, LP only uses its own cache.

Example
use-server-uuid-cache: false

storage-method

Which storage method the plugin should use.

See here for a full list of supported types.

Accepts: mysql, mariadb, postgresql, sqlite, h2, json, yaml, hocon, mongodb

If your MySQL server supports it, the mariadb option is preferred over mysql. h2 is also generally preferred over sqlite.

Example
storage-method: h2

data

This section is used for specifying credentials used for storage methods.

  • address - the host to be used for the database. Uses the standard DB engine port by default. If you have a non-default port, specify it here using host:port.
  • database - the database which should be used by LuckPerms
  • username - the username to be used
  • password - the password to be used. Leave empty to use no authentication.
Example
data:
  address: localhost
  database: minecraft
  username: root
  password: ''

pool-settings

These settings apply to the MySQL connection pool. The default values will be suitable for the majority of users. Do not change these settings unless you know what you're doing!

Sets the maximum size of the MySQL connection pool. Basically this value will determine the maximum number of actual connections to the database backend. More information about determining the size of connection pools can be found here:

https://github.com/brettwooldridge/HikariCP/wiki/About-Pool-Sizing

Example
data:
  pool-settings:
    maximum-pool-size: 10

split-storage

The split storage section allows you to use multiple storage options for different types of data.

The different types of data are:

  • user - data about users, including their permissions, parents and meta
  • group - data about groups, including their permissions, parents and meta
  • track - data about tracks (or so called "ladders")
  • uuid - a cache of uuid <-- --> username used by LuckPerms when usernames are used in the /lp user command instead of uuids.
  • log - the action log stored by LuckPerms

The allowed storage types are detailed above.

Example
split-storage:
  enabled: true
  methods:
    user: mariadb
    group: yaml
    track: yaml
    uuid: mariadb
    log: mariadb

sync-minutes

This option controls how frequently LuckPerms will perform a sync task.

A sync task will refresh all data from the storage, and ensure that the most up-to-date data is being used by the plugin.

This is disabled by default, as most users will not need it. However, if you're using a remote storage type without a messaging service setup, you may wish to set this value to something like 3.

Set to -1 to disable the task completely.

Example
data:
  sync-minutes: 3

watch-files

When using a file-based storage type, LuckPerms will monitor the data files for changes, and then schedule automatic updates when changes are detected.

If you don't want this to happen, set this option to false.

Example
watch-files: true

messaging-service

Settings for the messaging service.

If enabled and configured, LuckPerms will use the messaging system to inform other connected servers of changes. Use the command "/luckperms networksync" to push changes. Data is NOT stored using this service. It is only used as a messaging platform.

If you decide to enable this feature, you should set "sync-minutes" to -1, as there is no need for LuckPerms to poll the database for changes.

Available options:

  • sql - uses the SQL database to form a queue system for communication. Will only work when storage-method is set to MySQL or MariaDB. This is chosen by default when the option is set to 'none' and SQL storage is in use. Set to notsql to disable this.
  • pluginmsg - uses the plugin messaging channels to communicate. LuckPerms must be installed on your BungeeCord/Velocity proxy & all connected backend servers. This won't work if you have multiple proxies. The option needs to be set on all LP instances. Using sql is recommended over this option!
  • lilypad - uses LilyPad's pub sub to push changes. You need to have the LilyPad-Connect plugin installed.
  • redis - uses Redis pub sub to push changes.
  • none - nothing!
Example
messaging-service: none

auto-push-updates

If LuckPerms should automatically push updates after a change has been made with a command.

Example
auto-push-updates: true

push-log-entries

If LuckPerms should push logging entries to connected servers via the messaging service.

Example
push-log-entries: true

broadcast-received-log-entries

If LuckPerms should broadcast received logging entries to players on this platform.

If you have LuckPerms installed on your backend servers as well as a BungeeCord proxy, you should set this option to false on either your backends or your proxies, to avoid players being messaged twice about log entries.

Example
broadcast-received-log-entries: true

redis

Settings for Redis.

  • address - the host to be used for redis. Uses the standard port by default (6379). If you have a non-default port, specify it here using host:port.
  • password - the password to be used. Leave empty to use no authentication.
Example
redis:
  enabled: true
  address: localhost
  password: 'passw0rd'

temporary-add-behaviour

Controls how temporary permissions/parents/meta should be accumulated. The default behaviour is deny.

  • accumulate - the duration of any existing nodes will just be added to the new duration
  • replace - the longest duration will be kept, any others nodes will be forgotten
  • deny - the command will just fail if you try to add a duplicate temporary node
Example
temporary-add-behaviour: deny

primary-group-calculation

How should LuckPerms determine a users "primary" group. The default behaviour for Bukkit/Bungee is stored, and the default for Sponge is parents-by-weight.

  • stored - use the value stored against the users record in the file/database
  • parents-by-weight - use the users most highly weighted parent
  • all-parents-by-weight - same as above, but calculates based upon all parents inherited from both directly and indirectly
Example
primary-group-calculation: stored

argument-based-command-permissions

If LuckPerms should run extra permission checks when a player uses commands to modify permission data.

This system is documented in detail here.

Example
argument-based-command-permissions: true

log-notify

If the plugin should send log notifications to users whenever permissions are modified. Notifications are only sent to those with the appropriate permission to recieve the notification.

Notifications can also be disabled temporarily in-game using /lp log notify off

Example
log-notify: true

meta-formatting

How LuckPerms should form prefixes and suffixes.

This system is documented in detail here.

inheritance-traversal-algorithm

The algorithm LuckPerms should use when traversing the "inheritance tree".

Example
inheritance-traversal-algorithm: depth-first-pre-order

include-global

If players on this server should have their global permissions applied. (permissions that were not set with a specific server).

If this option is set to false, only permissions that were specifically set to apply on this server will apply. Do not set to false if the "server" option above is set to global. More details about how server specific permissions are groups work can be found here.

Example
include-global: true

include-global-world

Similar to the option above, except this works with worlds. If set to false, only permissions that are set in specific worlds will be given to users. Any permissions set without a specific world context will not be applied.

Example
include-global-world: true

apply-global-groups

This option operates in the same manner as "include-global", except changes the setting for group inheritance.

When calculating a players permissions, the plugin will scale the inheritance tree, resolving group memberships recursively. If this setting is set to false, and as a result, a group is not "applied", then none of that groups parents will be considered, and the inheritance lookup will stop at that point.

This means that even if a player indirectly inherits a group on a specific server, the group will not be applied if it is inherited through a non-server specific group.

For example, with this setting false, and the following setup:

User "Luck" inherits from group "admin" globally, and admin inherits from "default" on a specific server.

Even though Luck inherits default on the specific server, it will not be applied, because the inheritance lookup stops at admin. The parent groups of admin are therefore never even considered.

Example
apply-global-groups: true

apply-global-world-groups

Similar to the option above, except this works with worlds. If set to false, only groups that are set in specific worlds will be assigned and resolved for users. Any groups set without a specific world context will not be applied.

Example
apply-global-world-groups: true

apply-wildcards

If the plugin should apply wildcard permissions.

If plugin authors do not provide their own wildcard permissions, then enabling this option will allow LuckPerms to parse them instead. Bukkit especially did not endorse this practice, however it has become common among server administrators. On Sponge, this setting control whether "node.part.*" style wildcards will function.

Example
apply-wildcards: true

apply-regex

If the plugin should parse regex permissions.

If set to true, LuckPerms will detect any regex permissions, marked with "r=" at the start of the node, and return all requests matching the node. If you do not have any regex permissions setup, enabling this option will have no impact on performance. More info on this feature can be found here.

Example
apply-regex: true

apply-shorthand

If the plugin should resolve and apply any shorthand (GLOB style) permissions.

More info on this feature can be found here.

Example
apply-shorthand: true

apply-bukkit-child-permissions

If the plugin should apply Bukkit child permissions.

Plugin authors can define custom permissions structures for their plugin, which will be resolved and used by LuckPerms if this setting is enabled.

This is enabled by default, as it is a standard Bukkit feature, which most server admins expect to work. However, if you'd prefer not to use this system, it can be safely disabled.

Example
apply-bukkit-child-permissions: true

apply-bukkit-default-permissions

If the plugin should apply Bukkit default permissions.

Plugin authors can define permissions which should be given to all users by default, or setup permissions which should/shouldn't be given to opped players. If this option is set to false, LuckPerms will ignore these defaults.

This is enabled by default, as it is a standard Bukkit feature, which most server admins expect to work. However, if you'd prefer not to use this system, it can be safely disabled.

Example
apply-bukkit-default-permissions: true

apply-bukkit-attachment-permissions

If the plugin should apply Bukkit attachment permissions.

Other plugins on the server are able to add their own "permission attachments" to players. This allows them to grant players additional permissions which last until the end of the session, or until they're removed. If this option is set to false, LuckPerms will not include these attachment permissions when considering if a player should have access to a certain permission.

You may also see a slight performance improvement by enabling this feature. Combined with disabling the OP system, this system can be quite effective at disabling malicious attempts by plugins to grant arbitrary permissions to players.

This is enabled by default, as it is a standard Bukkit feature, which most server admins expect to work. However, if you'd prefer not to use this system, it can be safely disabled.

Example
apply-bukkit-attachment-permissions: true

apply-bungee-config-permissions

If the plugin should apply the permissions & groups defined in the BungeeCord config.yml

If set to false, LuckPerms will ignore these values.

This is disabled by default, as permissions should really be defined within LuckPerms, so they can be viewed and edited in-game alongside everything else.

Example
apply-bungee-config-permissions: false

apply-sponge-implicit-wildcards

If the plugin should resolve and apply permissions according to Sponge's implicit wildcard inheritance system.

That being: If a user has been granted example, then the player should have also be automatically granted example.function, example.another, example.deeper.nesting, and so on.

If this option is set to false, this system will not be applied.

This is enabled by default, as it is a standard Sponge feature, which most server admins / plugin authors expect to work. However, if you'd prefer not to use this system, it can be disabled.

Example
apply-sponge-implicit-wildcards=true

apply-sponge-default-subjects

If the plugin should apply Sponge default subject permissions.

Plugins can manipulate a set of default permissions granted to all users. If this option is set to false, the plugin will ignore this data when considering if a player has a permission.

This is enabled by default, as it is a standard Sponge feature, which most server admins / plugin authors expect to work. However, if you'd prefer not to use this system, it can be disabled.

Example
apply-sponge-default-subjects=true

world-rewrite

Allows you to set "aliases" for the worlds sent forward for context calculation. These aliases are provided in addittion to the real world name. Applied recursively.

Example
world-rewrite:
  world_nether: world
  world_the_end: world

enable-ops

If the vanilla OP system should be used.

If set to false, all users will be de-opped, and the op/deop commands will be disabled.

Example
enable-ops: true

auto-op

If set to true, any user with the permission "luckperms.autoop" will automatically be granted server operator status.

This permission can be inherited, or set on specific servers/worlds, temporarily, etc. Additionally, setting this to true will force the "enable-ops" option above to false. All users will be de-opped unless they have the permission node, and the op/deop commands will be disabled.

It is important to note that this setting is only checked when a player first joins the server, and when they switch worlds. Therefore, simply removing this permission from a user will not automatically de-op them. A player may need to relog to have the change take effect.

It is recommended that you use this option instead of assigning a single '*' permission.

Example
auto-op: false

commands-allow-op

If opped players should be allowed to use LuckPerms commands.

Set to false to only allow users who have the permissions access to the commands

Example
commands-allow-op: true

use-vault-server

If the vault-server option below should be used.

When this option is set to false, the server value defined above under "server" is used for Vault operations.

Example
use-vault-server: false

vault-server

The name of the server used within Vault operations.

If you don't want Vault operations to be server specific, set this to "global".

Will only take effect if use-vault-server is set to true above.

Example
vault-server: global

vault-include-global

If global permissions should be considered when retrieving meta or player groups.

Example
vault-include-global: true

vault-ignore-world

If Vault operations should ignore any world arguments if supplied.

By default, if a world argument is not supplied, permissions will be set on the players current world. (Vault design is just 10/10). Set this to true to change this behaviour.

Example
vault-ignore-world: false

vault-debug

If LuckPerms should print debugging info to console when a plugin uses a Vault function

Example
vault-debug: false

debug-logins

If LuckPerms should produce extra logging output when it handles logins.

Useful if you're having issues with UUID forwarding or data not being loaded.

The debug messages look like this:

[INFO]: [LP] Processing pre-login for c1d60c50-70b5-4722-8057-87767557e50d - Luck
[INFO]: UUID of player Luck is c1d60c50-70b5-4722-8057-87767557e50d
[INFO]: [LP] Processing login for c1d60c50-70b5-4722-8057-87767557e50d - Luck
[INFO]: Luck[/xxx:xxx] logged in with entity id xxx at ([xxx]x, x, x)
Example
debug-logins: false

allow-invalid-usernames

If set to true, LuckPerms will allow usernames with non alphanumeric characters.

Note that due to the design of the storage implementation, usernames must still be 16 characters or less.

Example
allow-invalid-usernames: false

prevent-primary-group-removal

If set to false, the plugin will allow a user's primary group to be removed with the parent remove command, and will set their primary group back to default.

Example
prevent-primary-group-removal: false

contexts.json

The contexts.json file is found alongside the main LuckPerms configuration file, and allows you to set two things.

Static Contexts

Static contexts are contexts which never change, and are granted to all players on the server by default.

LuckPerms provides one static context by default, called "server". This value is set using the server option in the main configuration file.

For example, if in my network, I have 3 factions servers, each with distinct names. The in LP config of each server, I have the server names set to factions1, factions2 and factions3. However, I want to grant a permission on all of the servers.

To achieve this, on all of the factions servers, I can add a static context called servertype and set it to factions.

{
  "static-contexts": {
  	"servertype": "factions"
  },
}

Then, I can use /lp group default permission set some.permission true servertype=factions to set a permission on all of the factions servers.

Default Contexts

Default contexts are contexts which are used by default in all commands executed on the server, if nothing is specifically specified.

{
  "default-contexts": {
  	"server": "survival"
  },
}

With the above set, running /lp user Luck permission set some.permission true would set some.permission to true for me in the server=survival context.