diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/api/admin_api.md | 31 | ||||
| -rw-r--r-- | docs/api/differences_in_mastoapi_responses.md | 43 | ||||
| -rw-r--r-- | docs/config.md | 77 |
3 files changed, 122 insertions, 29 deletions
diff --git a/docs/api/admin_api.md b/docs/api/admin_api.md index 8befa8ea0..75fa2ee83 100644 --- a/docs/api/admin_api.md +++ b/docs/api/admin_api.md @@ -8,15 +8,20 @@ Authentication is required and the user must be an admin. - Method `GET` - Query Params: - - *optional* `query`: **string** search term + - *optional* `query`: **string** search term (e.g. nickname, domain, nickname@domain) - *optional* `filters`: **string** comma-separated string of filters: - `local`: only local users - `external`: only external users - `active`: only active users - `deactivated`: only deactivated users + - `is_admin`: users with admin role + - `is_moderator`: users with moderator role - *optional* `page`: **integer** page number - *optional* `page_size`: **integer** number of users per page (default is `50`) -- Example: `https://mypleroma.org/api/pleroma/admin/users?query=john&filters=local,active&page=1&page_size=10` + - *optional* `tags`: **[string]** tags list + - *optional* `name`: **string** user display name + - *optional* `email`: **string** user email +- Example: `https://mypleroma.org/api/pleroma/admin/users?query=john&filters=local,active&page=1&page_size=10&tags[]=some_tag&tags[]=another_tag&name=display_name&email=email@example.com` - Response: ```JSON @@ -40,7 +45,7 @@ Authentication is required and the user must be an admin. } ``` -## `/api/pleroma/admin/user` +## `/api/pleroma/admin/users` ### Remove a user @@ -58,7 +63,7 @@ Authentication is required and the user must be an admin. - `password` - Response: User’s nickname -## `/api/pleroma/admin/user/follow` +## `/api/pleroma/admin/users/follow` ### Make a user follow another user - Methods: `POST` @@ -68,7 +73,7 @@ Authentication is required and the user must be an admin. - Response: - "ok" -## `/api/pleroma/admin/user/unfollow` +## `/api/pleroma/admin/users/unfollow` ### Make a user unfollow another user - Methods: `POST` @@ -111,7 +116,7 @@ Authentication is required and the user must be an admin. - `nickname` - `tags` -## `/api/pleroma/admin/permission_group/:nickname` +## `/api/pleroma/admin/users/:nickname/permission_group` ### Get user user permission groups membership @@ -126,7 +131,7 @@ Authentication is required and the user must be an admin. } ``` -## `/api/pleroma/admin/permission_group/:nickname/:permission_group` +## `/api/pleroma/admin/users/:nickname/permission_group/:permission_group` Note: Available `:permission_group` is currently moderator and admin. 404 is returned when the permission group doesn’t exist. @@ -160,7 +165,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret - On success: JSON of the `user.info` - Note: An admin cannot revoke their own admin status. -## `/api/pleroma/admin/activation_status/:nickname` +## `/api/pleroma/admin/users/:nickname/activation_status` ### Active or deactivate a user @@ -198,7 +203,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret - Response: - On success: URL of the unfollowed relay -## `/api/pleroma/admin/invite_token` +## `/api/pleroma/admin/users/invite_token` ### Get an account registration invite token @@ -210,7 +215,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret ] - Response: invite token (base64 string) -## `/api/pleroma/admin/invites` +## `/api/pleroma/admin/users/invites` ### Get a list of generated invites @@ -236,7 +241,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret } ``` -## `/api/pleroma/admin/revoke_invite` +## `/api/pleroma/admin/users/revoke_invite` ### Revoke invite by token @@ -259,7 +264,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret ``` -## `/api/pleroma/admin/email_invite` +## `/api/pleroma/admin/users/email_invite` ### Sends registration invite via email @@ -268,7 +273,7 @@ Note: Available `:permission_group` is currently moderator and admin. 404 is ret - `email` - `name`, optional -## `/api/pleroma/admin/password_reset` +## `/api/pleroma/admin/users/:nickname/password_reset` ### Get a password reset token for a given nickname diff --git a/docs/api/differences_in_mastoapi_responses.md b/docs/api/differences_in_mastoapi_responses.md index 3bb1bd41f..36b47608e 100644 --- a/docs/api/differences_in_mastoapi_responses.md +++ b/docs/api/differences_in_mastoapi_responses.md @@ -1,6 +1,6 @@ # Differences in Mastodon API responses from vanilla Mastodon -A Pleroma instance can be identified by "<Mastodon version> (compatible; Pleroma <version>)" present in `version` field in response from `/api/v1/instance` +A Pleroma instance can be identified by "<Mastodon version> (compatible; Pleroma <version>)" present in `version` field in response from `/api/v1/instance` ## Flake IDs @@ -38,9 +38,18 @@ Has these additional fields under the `pleroma` object: - `tags`: Lists an array of tags for the user - `relationship{}`: Includes fields as documented for Mastodon API https://docs.joinmastodon.org/api/entities/#relationship -- `is_moderator`: boolean, true if user is a moderator -- `is_admin`: boolean, true if user is an admin +- `is_moderator`: boolean, nullable, true if user is a moderator +- `is_admin`: boolean, nullable, true if user is an admin - `confirmation_pending`: boolean, true if a new user account is waiting on email confirmation to be activated +- `hide_followers`: boolean, true when the user has follower hiding enabled +- `hide_follows`: boolean, true when the user has follow hiding enabled + +### Source + +Has these additional fields under the `pleroma` object: + +- `show_role`: boolean, nullable, true when the user wants his role (e.g admin, moderator) to be shown +- `no_rich_text` - boolean, nullable, true when html tags are stripped from all statuses requested from the API ## Account Search @@ -60,3 +69,31 @@ Additional parameters can be added to the JSON body/Form data: - `preview`: boolean, if set to `true` the post won't be actually posted, but the status entitiy would still be rendered back. This could be useful for previewing rich text/custom emoji, for example. - `content_type`: string, contain the MIME type of the status, it is transformed into HTML by the backend. You can get the list of the supported MIME types with the nodeinfo endpoint. + +## PATCH `/api/v1/update_credentials` + +Additional parameters can be added to the JSON body/Form data: + +- `no_rich_text` - if true, html tags are stripped from all statuses requested from the API +- `hide_followers` - if true, user's followers will be hidden +- `hide_follows` - if true, user's follows will be hidden +- `hide_favorites` - if true, user's favorites timeline will be hidden +- `show_role` - if true, user's role (e.g admin, moderator) will be exposed to anyone in the API +- `default_scope` - the scope returned under `privacy` key in Source subentity + +## Authentication + +*Pleroma supports refreshing tokens. + +`POST /oauth/token` +Post here request with grant_type=refresh_token to obtain new access token. Returns an access token. + +## Account Registration +`POST /api/v1/accounts` + +Has theses additionnal parameters (which are the same as in Pleroma-API): + * `fullname`: optional + * `bio`: optional + * `captcha_solution`: optional, contains provider-specific captcha solution, + * `captcha_token`: optional, contains provider-specific captcha token + * `token`: invite token required when the registerations aren't public. diff --git a/docs/config.md b/docs/config.md index 7b6631f9b..470f71b7c 100644 --- a/docs/config.md +++ b/docs/config.md @@ -37,7 +37,7 @@ This filter replaces the filename (not the path) of an upload. For complete obfu An example for Sendgrid adapter: -```exs +```elixir config :pleroma, Pleroma.Emails.Mailer, adapter: Swoosh.Adapters.Sendgrid, api_key: "YOUR_API_KEY" @@ -45,7 +45,7 @@ config :pleroma, Pleroma.Emails.Mailer, An example for SMTP adapter: -```exs +```elixir config :pleroma, Pleroma.Emails.Mailer, adapter: Swoosh.Adapters.SMTP, relay: "smtp.gmail.com", @@ -105,11 +105,17 @@ config :pleroma, Pleroma.Emails.Mailer, * `safe_dm_mentions`: If set to true, only mentions at the beginning of a post will be used to address people in direct messages. This is to prevent accidental mentioning of people when talking about them (e.g. "@friend hey i really don't like @enemy"). (Default: `false`) * `healthcheck`: if set to true, system data will be shown on ``/api/pleroma/healthcheck``. +## :app_account_creation +REST API for creating an account settings +* `enabled`: Enable/disable registration +* `max_requests`: Number of requests allowed for creating accounts +* `interval`: Interval for restricting requests for one ip (seconds) + ## :logger * `backends`: `:console` is used to send logs to stdout, `{ExSyslogger, :ex_syslogger}` to log to syslog, and `Quack.Logger` to log to Slack An example to enable ONLY ExSyslogger (f/ex in ``prod.secret.exs``) with info and debug suppressed: -``` +```elixir config :logger, backends: [{ExSyslogger, :ex_syslogger}] @@ -118,7 +124,7 @@ config :logger, :ex_syslogger, ``` Another example, keeping console output and adding the pid to syslog output: -``` +```elixir config :logger, backends: [:console, {ExSyslogger, :ex_syslogger}] @@ -130,7 +136,7 @@ config :logger, :ex_syslogger, See: [logger’s documentation](https://hexdocs.pm/logger/Logger.html) and [ex_syslogger’s documentation](https://hexdocs.pm/ex_syslogger/) An example of logging info to local syslog, but warn to a Slack channel: -``` +```elixir config :logger, backends: [ {ExSyslogger, :ex_syslogger}, Quack.Logger ], level: :info @@ -156,14 +162,30 @@ Frontends can access these settings at `/api/pleroma/frontend_configurations` To add your own configuration for PleromaFE, use it like this: -`config :pleroma, :frontend_configurations, pleroma_fe: %{redirectRootNoLogin: "/main/all", ...}` +```elixir +config :pleroma, :frontend_configurations, + pleroma_fe: %{ + theme: "pleroma-dark", + # ... see /priv/static/static/config.json for the available keys. +}, + masto_fe: %{ + showInstanceSpecificPanel: true + } +``` -These settings need to be complete, they will override the defaults. See `priv/static/static/config.json` for the available keys. +These settings **need to be complete**, they will override the defaults. + +NOTE: for versions < 1.0, you need to set [`:fe`](#fe) to false, as shown a few lines below. ## :fe __THIS IS DEPRECATED__ -If you are using this method, please change it to the `frontend_configurations` method. Please set this option to false in your config like this: `config :pleroma, :fe, false`. +If you are using this method, please change it to the [`frontend_configurations`](#frontend_configurations) method. +Please **set this option to false** in your config like this: + +```elixir +config :pleroma, :fe, false +``` This section is used to configure Pleroma-FE, unless ``:managed_config`` in ``:instance`` is set to false. @@ -205,6 +227,7 @@ This section is used to configure Pleroma-FE, unless ``:managed_config`` in ``:i * `enabled`: Enables proxying of remote media to the instance’s proxy * `base_url`: The base URL to access a user-uploaded file. Useful when you want to proxy the media files via another host/CDN fronts. * `proxy_opts`: All options defined in `Pleroma.ReverseProxy` documentation, defaults to `[max_body_length: (25*1_048_576)]`. +* `whitelist`: List of domains to bypass the mediaproxy ## :gopher * `enabled`: Enables the gopher interface @@ -273,7 +296,7 @@ their ActivityPub ID. An example: -```exs +```elixir config :pleroma, :mrf_user_allowlist, "example.org": ["https://example.org/users/admin"] ``` @@ -302,7 +325,7 @@ the source code is here: https://github.com/koto-bank/kocaptcha. The default end Allows to set a token that can be used to authenticate with the admin api without using an actual user by giving it as the 'admin_token' parameter. Example: -```exs +```elixir config :pleroma, :admin_token, "somerandomtoken" ``` @@ -386,7 +409,7 @@ Configuration for the `auto_linker` library: Example: -```exs +```elixir config :auto_linker, opts: [ scheme: true, @@ -427,15 +450,36 @@ Pleroma account will be created with the same name as the LDAP user name. * `base`: LDAP base, e.g. "dc=example,dc=com" * `uid`: LDAP attribute name to authenticate the user, e.g. when "cn", the filter will be "cn=username,base" +## BBS / SSH access + +To enable simple command line interface accessible over ssh, add a setting like this to your configuration file: + +```exs +app_dir = File.cwd! +priv_dir = Path.join([app_dir, "priv/ssh_keys"]) + +config :esshd, + enabled: true, + priv_dir: priv_dir, + handler: "Pleroma.BBS.Handler", + port: 10_022, + password_authenticator: "Pleroma.BBS.Authenticator" +``` + +Feel free to adjust the priv_dir and port number. Then you will have to create the key for the keys (in the example `priv/ssh_keys`) and create the host keys with `ssh-keygen -N "" -b 2048 -t rsa -f ssh_host_rsa_key`. After restarting, you should be able to connect to your Pleroma instance with `ssh username@server -p $PORT` + ## :auth +* `Pleroma.Web.Auth.PleromaAuthenticator`: default database authenticator +* `Pleroma.Web.Auth.LDAPAuthenticator`: LDAP authentication + Authentication / authorization settings. * `auth_template`: authentication form template. By default it's `show.html` which corresponds to `lib/pleroma/web/templates/o_auth/o_auth/show.html.eex`. * `oauth_consumer_template`: OAuth consumer mode authentication form template. By default it's `consumer.html` which corresponds to `lib/pleroma/web/templates/o_auth/o_auth/consumer.html.eex`. * `oauth_consumer_strategies`: the list of enabled OAuth consumer strategies; by default it's set by OAUTH_CONSUMER_STRATEGIES environment variable. -# OAuth consumer mode +## OAuth consumer mode OAuth consumer mode allows sign in / sign up via external OAuth providers (e.g. Twitter, Facebook, Google, Microsoft, etc.). Implementation is based on Ueberauth; see the list of [available strategies](https://github.com/ueberauth/ueberauth/wiki/List-of-Strategies). @@ -459,7 +503,7 @@ Note: make sure that `"SameSite=Lax"` is set in `extra_cookie_attrs` when you ha Once the app is configured on external OAuth provider side, add app's credentials and strategy-specific settings (if any — e.g. see Microsoft below) to `config/prod.secret.exs`, per strategy's documentation (e.g. [ueberauth_twitter](https://github.com/ueberauth/ueberauth_twitter)). Example config basing on environment variables: -``` +```elixir # Twitter config :ueberauth, Ueberauth.Strategy.Twitter.OAuth, consumer_key: System.get_env("TWITTER_CONSUMER_KEY"), @@ -488,6 +532,13 @@ config :ueberauth, Ueberauth, ] ``` +## OAuth 2.0 provider - :oauth2 + +Configure OAuth 2 provider capabilities: + +* `token_expires_in` - The lifetime in seconds of the access token. +* `issue_new_refresh_token` - Keeps old refresh token or generate new refresh token when to obtain an access token. + ## :emoji * `shortcode_globs`: Location of custom emoji files. `*` can be used as a wildcard. Example `["/emoji/custom/**/*.png"]` * `groups`: Emojis are ordered in groups (tags). This is an array of key-value pairs where the key is the groupname and the value the location or array of locations. `*` can be used as a wildcard. Example `[Custom: ["/emoji/*.png", "/emoji/custom/*.png"]]` |