diff --git a/DOCUMENTATION/code_walkthrough.md b/DOCUMENTATION/DEVELOPERS/code_walkthrough.md similarity index 100% rename from DOCUMENTATION/code_walkthrough.md rename to DOCUMENTATION/DEVELOPERS/code_walkthrough.md diff --git a/DOCUMENTATION/database/database.pdf b/DOCUMENTATION/DEVELOPERS/database/database.pdf similarity index 100% rename from DOCUMENTATION/database/database.pdf rename to DOCUMENTATION/DEVELOPERS/database/database.pdf diff --git a/DOCUMENTATION/DEVELOPERS/install.md b/DOCUMENTATION/DEVELOPERS/install.md new file mode 120000 index 0000000000..5f52b2be3c --- /dev/null +++ b/DOCUMENTATION/DEVELOPERS/install.md @@ -0,0 +1 @@ +../../INSTALL.md \ No newline at end of file diff --git a/DOCUMENTATION/SYSTEM_ADMINISTRATORS/CONFIGURE.md b/DOCUMENTATION/SYSTEM_ADMINISTRATORS/CONFIGURE.md new file mode 100644 index 0000000000..09d5651f77 --- /dev/null +++ b/DOCUMENTATION/SYSTEM_ADMINISTRATORS/CONFIGURE.md @@ -0,0 +1,762 @@ +Configuration options +================================================================================ + +The configuration for GNU social is stored in the database table +`config`. + +A Web based configuration panel exists so the site admin can configure +GNU social. The preferred method for changing config options is to use this +panel. + +A command-line script, `set_config.php`, can be used to set individual +configuration options. It's in the `bin/` directory. + +Almost all configuration options are made through a two-dimensional +associative array, cleverly named `$config`. A typical configuration +line will be: + + $config['section']['setting] = value; + +The following documentation describes each section and setting. + + +site +------------------------------------------------------------------------------- + +This section is a catch-all for site-wide variables. + +* `name` (string, required, defaults to the value provided in the configre script, + sitename): the name of your site, like 'YourCompany Microblog'. + +* `server` (string, required, defaults to the value provided in the configre script, + sitename): the server domain, like 'example.net'. + +* `notice` (string, default null): A plain string that will appear on every page. A good + place to put introductory information about your service, or info about upgrades and + outages, or other community info. Any HTML will be escaped. + +* `theme` (string, default 'default'): Theme for your site (see Theme section). + +* `logo` (string, default null): URL of an image file to use as the logo for the site. + Overrides the logo in the theme, if any. + +* `language` (string, default "en"): default language for your site. Defaults to English. + Note that this is overridden, if enabled in the following setting, if a user is logged + in and has selected a different language or if the user is NOT logged in, but their + browser requests a different langauge. Since pretty much everybody's browser requests + a language, that means that changing this setting has little or no effect in practice. + +* `detect_language` (boolean, default true): whether to use the most appropriate language + depending on the requester's browser preferences. + +* `languages` (array, default null): A list of languages supported on your site. Typically + you'd only change this if you wanted to disable support for one or more languages: + + `unset($config['site']['languages']['de'])` will disable support for German. + +* `email` (string, required): contact email address for your site. By default, it's + extracted from your Web server environment or the value provided in the configure + script; you may want to customize it. + +* `recovery_disclose` (boolean, default false): whether to confirm if the email exists + when attempting to login. Recommended to keep it false, for some privacy. + +* `timezone` (string, default 'UTC'): default timezone for message display. Users + can set their own time zone. Defaults to 'UTC', which is a pretty good + default. + +* `brought_by` (string, default null): text used for the "brought by" link. + +* `brought_by_url` (string, default null): name of an organization or individual who + provides the service. Each page will include a link to this name in the footer or + sidebar. A good way to link to the blog, forum, wiki, corporate portal, or whoever is + making the service available. + +* `closed` (boolean, default false): If set to 'true', will disallow registration on your + site. This is a easy way to restrict accounts to only one individual or group; just + register the accounts you want on the service, *then* set this variable to 'true'. + +* `invite_only` (boolean, default false): If set to 'true', will only allow registration + if the user was invited by an existing user. + +* `private` (boolean, default false): If set to 'true', anonymous users will be redirected + to the 'login' page. Also, API methods that normally require no authentication will + require it. Note that this does not turn off registration; use 'closed' or + 'invite_only' for that behaviour. + +* `ssl` (enum['always', 'sometimes', 'never'], default always'): Whether to use SSL and + https:// URLs for some or all pages. + + Possible values are 'always' (use it for all pages), 'never' (don't use it for any + pages), or 'sometimes' (use it for sensitive pages that include passwords like login + and registration, but not for regular pages). + +* `ssl_proxy` (string|boolean, default false): Whether to force GNUsocial to think it is + HTTPS when the server gives no such information. I.e. when you're using a reverse + proxy that adds the encryption layer but the webserver that runs PHP isn't configured + with a key and certificate. If a string is given, it will be used as the URL of the + proxy server. + +* `duplicate_time_limit` (integer, default 60): minimum time allowed for one person to say + the same thing twice. Default 60s. If it happens faster than this, it's considered a + user or UI error. + +* `text_limit` (integer, default 1000): default max size for texts in the site. Can be + fine-tuned for notices, messages, profile bios and group descriptions. Zero indicates + no limit. + +* `x-static-delivery` (string, default null): when a string, use this as the header with + which to serve static files. Possible values are 'X-Sendfile' (for Apache and others) + and 'X-Accel-Redirect' (for nginx). + + +security +------------------------------------------------------------------------------- + +* `hash_algos` (array, default ['sha1', 'sha256', 'sha512']): set to null for anything + that `hash_hmac()` can handle; can be any combination of the result of `hash_algos()` + + +db +------------------------------------------------------------------------------- + +* `mirror` (array, default null): you can set this to an array of database connection + URIs. If it's set, load will be split among these, and replication will be enabled. + + +fix +------------------------------------------------------------------------------- + +* `fancy_urls` (boolean, default true): fix any non-facy url to the correct form, when + possible. + +* `http` (boolean, default true): fixe any http links to https. + + +queue +------------------------------------------------------------------------------- + +You can configure the software to queue time-consuming tasks, like +sending out SMS, email or XMPP messages, for off-line processing. + +* `enabled` (boolean, default true): Whether to uses queues. + +* `daemon` (boolean, default false): Whether to use queuedaemon. False means + you'll use OpportunisticQM plugin. + +* `threads` (int): How many queue processes to run. Defaults to number of cpu cores in + unix-like systems or 1 on other OSes. + +* `subsystem` (enum["db", "stomp", "redis"], default 'db'): Which kind of + queueserver to use. Values include "db" for our database queuing (no other server + required), "stomp" for a stomp server amd "redis" for a Redis server. + +* `basename` (string, default '/queue/gnusocial/'): a root name to use for queues (stomp + and redis only). Typically something like '/queue/sitename/' makes sense. If running + multiple instances on the same server, make sure that either this setting or + `$config['site']['nickname']` are unique for each site to keep them separate. + +* `control_channel` (string, default '/topic/gnusocial/control'): the control channel used + for different queue processes to communicate. + +* `monitor` (string, default null): URL endpoint to monitor queue status + +* `soft_limit` (string, default '90%'): an absolute or relative "soft memory limit"; + daemons will restart themselves gracefully when they find they've hit this amount of + memory usage. Relative means a percentage of PHP's global `memory_limit` setting. + +* `spawn_delay` (integer, default 1): seconds to wait between deamon restarts. + +* `debug_memory` (boolean, default false): log daemon's memory usage. + +* `stomp_server` (string, default null): URI for stomp server. Something like + "tcp://hostname:61613". More complicated ones are possible; see your stomp server's + documentation for details. + +* `stomp_username` (string, default null): username for connecting to the stomp server. + +* `stomp_password` (string, default null): password for connecting to the stomp server. + +* `stomp_persistent` (boolean, default true): Keep items across queue server restart, if + enabled. Note: Under ActiveMQ, the server configuration determines if and how + persistent storage is actually saved. Not all stomp servers support persistence. + +* `stomp_transactions` (boolean, default true): use transactions to aid in error + detection. A broken transaction will be seen quickly, allowing a message to be + redelivered immediately if a daemon crashes. Not all stop servers support + transactions. + +* `stomp_acks` (boolean, default true): send acknowledgements to aid in flow control. An + acknowledgement of successful processing tells the server we're ready for more and can + help keep things moving smoothly. This should *not* be turned off when running with + ActiveMQ, (it breaks if you do), but if using another message queue server that does + not support acknowledgements you might need to disable this. + +* `stomp_manual_failover` (boolean, default true): if multiple servers are listed, treat + them as separate (enqueue on one randomly, listen on all). + +* `max_retries` (integer, default 10): for stomp, drop messages after N failed + attempts to process. + +* `dead_letter_dir` (string, default null): for stomp, optional directory to dump + data on failed queue processing events after discarding them. + + +avatar +------------------------------------------------------------------------------- + +* `server` (string, default null): If set, defines another server where avatars are + stored. Note that the `dir` still has to be writeable. You'd typically use this to + split HTTP requests on the client to speed up page loading, either with another + virtual server or with an NFS or SAMBA share. Clients typically only make 2 + connections to a single server at a time + , so this can + parallelize the job. + +* `url_base` (string, 'default '/avatar/'): URL where avatars can be found. + +* `ssl` (boolean, default null): Whether to access avatars using HTTPS. Defaults + to null, meaning to guess based on site-wide SSL settings. + +* `dir` (string, default 'file/avatar/'): Directory to save avatar files to. + +* `max_size_px` (integer, default 300): Maximum width or height for user avatars, in pixels + + +javascript +------------------------------------------------------------------------------- + +* `server` (string, default null): You can speed up page loading by pointing the + javascript file lookup to another server (virtual or real). Defaults to NULL, meaning + to use the site server. + +* `url_base` (string default '/js/'): URL part for JavaScript files. + +* `ssl` (boolean, default null): Whether to use SSL for JavaScript files. Default is null, + which means guess based on site SSL settings. + +* `bust_frames` (boolean, default true): If true, all web pages will break out of + framesets. If false, can comfortably live in a frame or iframe... probably. + + +attachments +------------------------------------------------------------------------------- + +* `server` (string, default null): Server name to use when creating URLs for uploaded + files. Defaults to null, meaning to use the default Web server. Using a virtual server + here can speed up Web performance. + +* `url_base` (string, default '/file/'): URL path, relative to the server, to find + files. Defaults to main path + '/file/'. + +* `ssl` (boolean, default null): Whether to use HTTPS for file URLs. Defaults to null, + meaning to use other SSL settings. + +* `dir` (string, default '/file/uploads/'): Directory accessible to the Web process where + uploads should go. + +* `supported` (array): An associative array of mime types you accept to store and + distribute, like 'image/gif', 'video/mpeg', 'audio/mpeg', to the corresponding file + extension. Make sure you setup your server to properly recognize the types you want to + support. It's important to use the result of calling `image_type_to_extension` for the + appropriate image type, in the case of images. This is so all parts of the code see + the same file extension for each image type (jpg vs jpeg). For example, to enable BMP + uploads, add this to the config.php file: + `image_type_to_mime_type(IMAGETYPE_BMP) => image_type_to_extension(IMAGETYPE_BMP);` See + https://www.php.net/manual/en/function.image-type-to-mime-type.php for a list of such + constants. If a filetype is not listed there, it's possible to add the mimetype and + the extension by hand, but they need to match those returned by the file command. + +For quotas, be sure you've set the `upload_max_filesize` and `post_max_size` in php.ini to +be large enough to handle your upload. In httpd.conf (if you're using apache), check that +the LimitRequestBody directive isn't set too low (it's optional, so it may not be there at +all). + +* `file_quota` (integer, defaults to minimum of `'post_max_size', 'upload_max_filesize', + 'memory_limit'`): Maximum size for a single file upload, in bytes. A user can send any + amount of notices with attachments as long as each attachment is smaller than + file_quota. + +* `user_quota` (integer, default 200M): Total size, in bytes, a user can store on this + server. Each user can store any number of files as long as their total size does not + exceed the user_quota. + +* `monthly_quota` (integer, default 20M): Total size in bytes that a user can upload each + month. + +* `uploads` (boolean, default true): Whether to allow uploading files with notices. + +* `show_html` (boolean, default true): Whether to show (filtered) text/html attachments + (and oEmbed HTML etc.). Doesn't affect AJAX calls. + +* `show_thumbs` (boolean, default true): Whether to show thumbnails in notice lists for + uploaded images, and photos and videos linked remotely that provide oEmbed info. + +* `process_links` (boolean, default true): Whether to follow redirects and save all + available file information (mimetype, date, size, oembed, etc.). + +* `ext_blacklist` (array, default []): associative array to either deny certain extensions or + change them to a different one. For example: + + $config['attachments']['extblacklist']['php'] = 'phps'; // this turns .php into .phps + $config['attachments']['extblacklist']['exe'] = false; // this would deny any uploads + // of files with the "exe" extension + +* `filename` (string, default hash): Name for new files, one of: 'upload', 'hash'. + +* `memory_limit` (string, default '1024M'): PHP memory limit to use temporarily when + handling images + + +thumbnail +------------------------------------------------------------------------------- + +* `server` (string, default null): Server name from which to serve thumbnails. Defaults to + null, meaning to use the default Web server. Using a virtual server here can speed up + Web performance. + +* `url_base` (string, default '/thumb/'): URL path, relative to the server, to find + files. + +* `ssl` (boolean, default null): Whether to use HTTPS for thumbnail URLs. Defaults to null, + meaning to use other SSL settings. + +* `dir` (string, default '/file/thumbnails/'): Path where to store thumbnails. + +* `crop` (boolean, default false): Whether to crop thumbnails (or scale them down) + +* `max_size_px` (integer, default 1000): Thumbnails with an edge greater than this will + not be generated. + +* `width` (integer, default 450): Width for generated thumbnails. + +* `height` (integer, default 600): Heigth for generated thumbnails. + +* `upscale` (boolean, default false): Whether to generate thumbnails bigger than the original. + +* `animated` (boolean, default false): Whether to allow animated thumbnails. + + +theme +------------------------------------------------------------------------------- + +* `server` (string, default null): Like avatars, you can speed up page loading + by pointing the theme file lookup to another server (virtual or real). + The default of null will use the same server as PA. + +* `url_base` (string, default '/theme'): Path part of theme URLs, before the theme name. + Relative to the theme server. It may make sense to change this path when upgrading, + (using version numbers as the path) to make sure that all files are reloaded by + caching clients or proxies. + +* `ssl` (boolean, default null): Whether to use SSL for theme elements. Default + is null, which means guess based on site SSL settings. + +* `dir` (string, default "./themes"): Directory where theme files are stored. + Used to determine whether to show parts of a theme file. Defaults to the + theme subdirectory of the install directory. + + +plugins +------------------------------------------------------------------------------- + +* `server` (string, default null): Server to find static files for a plugin when the page + is plain old HTTP. Defaults to site/server (same as pages). You can use this to move + plugin CSS and JS files to a CDN. + +* `url_base` (string, default '/plugins/'): Path to the plugin files. Expects that each + plugin will have a subdirectory at plugins/NameOfPlugin. Change this if you're using + a CDN. + +* `ssl` (boolean, default null) Whether to use ssl for files served by plugins. + +* `core` (associative array, default TODO): Core GNU social modules, cannot be disabled. + +* `default`: (associative array, default TODO): Mapping from plugin name to array of + plugin arguments. + +* `locale_path` (string, default null): Path for finding plugin locale files. In the + plugin's directory by default. + + +license +------------------------------------------------------------------------------- + +The default license to use for your users' notices. The default is the Creative Commons +Attribution 4.0 license, which is probably the right choice for any public site. Note that +some other servers will not accept notices if you apply a stricter license than this. + +* `type` (enum["cc", "allrightsreserved", "private"], default 'cc'): One of 'cc' (for + Creative Commons licenses), 'allrightsreserved' (default copyright), or 'private' (for + private and confidential information). + +* `owner` (string|boolean, default null): For 'allrightsreserved' or 'private', an + assigned copyright holder (for example, an employer for a private site). Use true to + attribute it to the poster. + +* `url` (string, default 'https://creativecommons.org/licenses/by/4.0/'): URL of the + license, used for links. + +* `title` (string, default 'Creative Commons Attribution 4.0'): Title for the license. + +* `image` (string, default '/theme/licenses/cc_by_4.0.png'): URL path for the license image. + + +mail +------------------------------------------------------------------------------- + +This is for configuring out-going email. + +* `backend` (enum["mail", "sendmail", "smtp"], default 'mail'): The backend to use for + mail. We recommend SMTP where your setup supports it as it is of the three the more + difficult one for script exploits to abuse (relatively speaking - they all have + potential problems.). + +* `params` (array, default null): If the mail backend requires any parameters, you can + provide them in this array. + +* `domain_check` (boolean, default true): Check email origin is valid. + + +nickname +------------------------------------------------------------------------------- + +* `blacklist` (array, default ['doc', 'main', 'avatar', 'theme']): an array of strings for + usernames that may not be registered. You may want to add others if you have other + software installed in a subdirectory of GNU social or if you just don't want certain + words used as usernames. + +* `featured` (array, default null): an array of nicknames of 'featured' users of the site. + Can be useful to draw attention to well-known users, or interesting people, or + whatever. + + +profile +------------------------------------------------------------------------------- + +* `banned` (array, defualt []): array of users to hell-ban + +* `bio_text_limit` (integer, default null): Max character length of bio; 0 means no + limit; null means to use the site text limit default. + +* `allow_nick_change` (boolean, default false): Whether to allow users to change their + nickname. + +* `allow_private_stream` (boolean, default true): Whether users can set their streams to + private, so only followers can see it. + +* `backup` (boolean, default false): Whether users can backup their own profiles. Can + cause DoS. + +* `restore` (boolean, default false): Whether users can restore their profiles from backup + files. Can cause DoS. + +* `delete` (boolean, default false): Whether users can delete their own accounts. + +* `move` (boolean, default false): Whether users can move their accounts to another + server. + + +image +------------------------------------------------------------------------------- + +* `jpegquality` {integer, default 85}: default quality to use when reencoding images as + jpeg. + + +theme_upload +------------------------------------------------------------------------------- + +* `enabled` (boolean, default true): Whether to allow users to upload themes + +* `formats` (array, default ['zip', 'tar', 'gz', 'tar.gz']): Formats to allow + +foaf +------------------------------------------------------------------------------- + +* `mbox_sha1sum` (boolean, default false): whether to include this box in the FOAF + protocol page + + +public +------------------------------------------------------------------------------- + +For configuring the public stream. + +* `local_only` (boolean, default false): If set to true, only messages posted by users of + this instance (rather than remote instances) are shown in the public stream. + +* `blacklist` (array, default []): An array of IDs of users to hide from the public + stream. Useful if you have someone making an excessive amount of posts to the site or + some kind of automated poster, testing bots, etc. + +* `exclude_sources` (array, default []): Sources of notices that should be kept off of + the public timeline (because they're from automatic posters, for instance). + + +throttle +------------------------------------------------------------------------------- + +For notice-posting throttles. + +* `enabled` (boolean, default true): Whether to throttle posting. + +* `count` (integer, default 20): Each user can make this many posts in 'timespan' seconds. + So, if count is 100 and timespan is 3600, then there can be only 100 posts from a user + every hour. + +* `timespan` (integer, default 600): See 'count'. + + +invite +------------------------------------------------------------------------------- + +* `enabled` (boolean, default true): Whether to allow users to send invites. + + +tag +------------------------------------------------------------------------------- + +* `dropoff` (integer, default 86400 * 10): Exponential decay factor for tag listing, in + seconds. You can twiddle with this to try to get better results for your site. + +* `cutoff` (integer, default 86400 * 90): Cutoff, in seconds, before which to not look for + notices. + + +popular +------------------------------------------------------------------------------- + +* `dropoff` (integer, default 86400 * 10): Exponential decay factor for popular notices, in + seconds. You can twiddle with this to try to get better results for your site. + +* `cutoff` (integer, default 86400 * 90): Cutoff, in seconds, before which to not look for + notices. + + +daemon +------------------------------------------------------------------------------- + +* `piddir` (string, default `sys_get_temp_dir()`): Directory that daemon processes should + write their PID file (process ID) to. + +* `user` (string|integer, default false): If set, the daemons will try to change their + effective user ID to this user before running. Probably a good idea, especially if you + start the daemons as root. + +* `group` (string|integer, default false): If set, the daemons will try to change their + effective group ID to this named group. + + +ping +------------------------------------------------------------------------------- + +Using the "XML-RPC Ping" method initiated by weblogs.com, the site can +notify third-party servers of updates. + +* `notify` (array, default []): An array of URLs for ping endpoints. + +* `timeout` (integer, default 2): Interval in seconds between notifications. + + +new_users +------------------------------------------------------------------------------- + +* `default_subscriptions` (array, default null): Nickname of user accounts to + automatically subscribe new users to. Typically this would be a system account for e.g. + service updates or announcements. Users are able to unsub if they want. + +* `welcome_user` (string, default null): Nickname of a user account that sends welcome + messages to new users. + +N.B. If either of these special user accounts are specified, the users should be created + before the configuration is updated. + + +linkify +------------------------------------------------------------------------------- + +* `bare_domain` (boolean, default false): Prepend schema to any linked domains (a href, + not display text). + +* `linkify_ipv4` (boolean, default false): Convert IPv4 addresses into hyperlinks. + +* `linkify_ipv6` (boolean, default false): Convert IPv6 addresses into hyperlinks. + + +group +------------------------------------------------------------------------------- + +* `max_aliases` (integer, default 3): Maximum number of aliases a group can have. + Set to 0 or less to prevent aliases in a group. + +* `description_limit` (integer, default null): Maximum number of characters to allow in + group descriptions. null means to use the site-wide text limits. 0 means no limit. + + +people_tag +------------------------------------------------------------------------------- + +* `max_tags` (integer, default 100): Maximum number of people tags a user can create. + +* `max_people` (integer, default 500): Maximum number of people with the same user people tag. + +* `allow_tagging` (associative array, default ['local' => true, 'remote' => true])>: Which + kind of user to allow tagging. + +* `description_limit` (integer, default null): Maximum tag description lenght. + + +search +------------------------------------------------------------------------------- + +* `type` (enum('fulltext', 'like'), default 'like'): type of search. Ignored if PostgreSQL + is enabled. Can either be 'fulltext' or 'like'. The former is faster and more + efficient but requires the lame old MyISAM engine for MySQL. The latter will work with + InnoDB but could be miserably slow on large systems. + + +html_filter +------------------------------------------------------------------------------- + +* `tags` (array, default ['img', 'video', 'audio', 'script']): Remove tags from + user/remotely generated HTML. + + +notice +------------------------------------------------------------------------------- + +* `content_limit` (integer, default null): Max length of the plain-text content of a + notice. Null means to use the site-wide text limit. 0 means no limit. + +* `allow_private` (boolean, default false): Whether to allow users to post notices visible + only to their subscribers. + +* `hide_banned` (boolean, default true): Whether to hide hell-banned users' notices. + + +message +------------------------------------------------------------------------------- + +* `content_limit` (integer, default null): Max length of the plain-text content of a + message. Null means to use the site-wide text limit. 0 means no limit. + + +location +------------------------------------------------------------------------------- + +* `share` (enum('always', 'user', 'never'), default 'user'): Whether to share user + location. 'user' means each user can choose. + + +admin +------------------------------------------------------------------------------- + +* `panels` (array, default ['site', 'user', 'paths', 'access', 'sessions', 'sitenotice', + 'license', 'plugins']): Which panels to include in the admin tab. + + +single_user +------------------------------------------------------------------------------- + +If an installation has only one user, this can simplify a lot of the +interface. It also makes the user's profile the root URL. + +* `enabled` (boolean, default value provided in configure): Whether to run in "single user mode". + +* `nickname` (string, default null): nickname of the single user. If no nickname is + specified, the site owner account will be used (if present). + + +robots_txt +------------------------------------------------------------------------------- + +* `crawl_delay` (integer, default 0): if non-zero, this value is provided as the + 'Crawl-Delay:' for the robots.txt file. see + for + more information. Default is zero, no explicit delay. + +* `disallow`(array, default ['main', 'settings', 'admin', 'search', 'message']): Array of + paths to disallow. Ignored when site is private, in which case the entire site ('/') + is disallowed. + + +nofollow +------------------------------------------------------------------------------- + +We optionally put 'rel="nofollow"' on some links in some pages. The following +configuration settings let you fine-tune how or when things are nofollowed. See +http://en.wikipedia.org/wiki/Nofollow for more information on what 'nofollow' means. + +* `subscribers` (boolean, default true): Whether to nofollow links to subscribers on the + profile and personal pages. + +* `members` (boolean, default true): Whether to nofollow links to members on the group + page. Default true. + +* `peopletag` (boolean, default true): Whether to nofollow links to people listed in the + peopletag page. Default true. + +* `external` (enum('always', 'sometimes', 'never'), default 'sometimes'): External links + in notices. One of three values: 'always', 'sometimes', 'never'. If 'sometimes', then + external links are not nofollowed on profile, notice, and favorites page. Default is + 'sometimes'. + + +url_shortener +------------------------------------------------------------------------------- + +* `service` (string, default 'internal'): URL shortening service to use by default. Users + can override individually. + +* `max_url_length` (integer, default 100): If an URL is strictly longer than this limit, + it will be shortened. Note that the URL shortener service may return an URL longer + than this limit. Users can override. If set to 0, all URLs will be shortened. + +* `max_notice_length` (integer, default null): If a notice is strictly longer than this + limit, all URLs in the notice will be shortened. Users can override this. + + +http +------------------------------------------------------------------------------- + +* `ssl_cafile` (string, default '/docker/certbot/files/live/'): location of the CA file + for SSL connections. If not set, peers won't be able to verify our identity. + +* `timeout` (integer, default `ini_get('default_socket_timeout')`): Timeout in seconds + when to close a connection. + +* `proxy_host` (string, default null): Host to use for proxying HTTP requests. If null, + doesn't use an HTTP proxy. + +* `proxy_port` (integer, default null): Port to use to connect to HTTP proxy host. + +* `proxy_user` (string, default null): Username to use for authenticating to the HTTP proxy. + +* `proxy_password` (string, default null): Password to use for authenticating to the HTTP proxy. + +* `proxy_auth_scheme` (TODO): Scheme to use for authenticating to the HTTP proxy. + + +discovery +------------------------------------------------------------------------------- + +* `CORS` (boolean, default false): Whether to allow Cross-Origin Resource Sharing for + service discovery (host-meta, XRD, etc.) + + +performance +------------------------------------------------------------------------------- + +* `high` (boolean, default fakse): Disables some high-performance-intensity components. + + +login_command +------------------------------------------------------------------------------- + +* `enabled` (boolean, default false): Whether to enable users to send the text 'login' to + the site through any channel and receive a link to login to the site automatically in + return. Possibly useful for users who primarily use an XMPP or SMS interface. Note + that the security implications of this are pretty serious. You should enable it only + after you've convinced yourself that it is safe. + diff --git a/DOCUMENTATION/SYSTEM_ADMINISTRATORS/install.md b/DOCUMENTATION/SYSTEM_ADMINISTRATORS/install.md new file mode 120000 index 0000000000..5f52b2be3c --- /dev/null +++ b/DOCUMENTATION/SYSTEM_ADMINISTRATORS/install.md @@ -0,0 +1 @@ +../../INSTALL.md \ No newline at end of file diff --git a/DOCUMENTATION/install.md b/DOCUMENTATION/install.md deleted file mode 120000 index 71db8b4934..0000000000 --- a/DOCUMENTATION/install.md +++ /dev/null @@ -1 +0,0 @@ -../INSTALL.md \ No newline at end of file diff --git a/src/Core/DefaultSettings.php b/src/Core/DefaultSettings.php index 3f87c92d23..a7a451d44e 100644 --- a/src/Core/DefaultSettings.php +++ b/src/Core/DefaultSettings.php @@ -31,6 +31,7 @@ namespace App\Core; use App\Entity\Config; +use App\Util\Common; use Symfony\Component\Config\Definition\Exception\Exception; abstract class DefaultSettings @@ -40,14 +41,13 @@ abstract class DefaultSettings { self::$defaults = ['site' => - ['name' => $_ENV['SOCIAL_SITENAME'], + ['name' => $_ENV['SOCIAL_SITENAME'] ?? 'Another social instance', + 'server' => $_ENV['SOCIAL_DOMAIN'] ?? 'localhost', 'notice' => null, // site wide notice text - 'theme' => 'neo-gnu', + 'theme' => 'default', 'logo' => null, - 'fancy' => true, - 'locale_path' => INSTALLDIR . '/translations', 'language' => 'en', - 'langdetect' => true, + 'detect_language' => true, 'languages' => I18n::get_all_languages(), 'email' => $_ENV['SERVER_ADMIN'] ?? $_ENV['SOCIAL_ADMIN_EMAIL'] ?? null, 'recovery_disclose' => false, // Whether to not say that we found the email in the database, when asking for recovery @@ -59,28 +59,26 @@ abstract class DefaultSettings 'private' => false, 'ssl' => 'always', 'ssl_proxy' => false, // set to true to force GNU social to think it is HTTPS (i.e. using reverse proxy to enable it) - 'ssl_proxy_server' => null, 'duplicate_time_limit' => 60, // default for same person saying the same thing 'text_limit' => 1000, // in chars; 0 == no limit - 'use_x_sendfile' => false, - 'description_limit' => null + 'x-static-delivery' => null, ], 'security' => ['hash_algos' => ['sha1', 'sha256', 'sha512']], // set to null for anything that hash_hmac() can handle (and is in hash_algos()) 'db' => ['mirror' => null], // TODO implement 'fix' => - ['fancyurls' => true, // makes sure aliases in WebFinger etc. are not f'd by index.php/ URLs - 'legacy_http' => false, // set this to true if you have upgraded your site from http=>https + ['fancy_urls' => true, // makes sure aliases in WebFinger etc. are not f'd by index.php/ URLs + 'http' => true, // set this to true if you have upgraded your site from http=>https ], 'queue' => ['enabled' => true, 'daemon' => false, // Use queuedaemon. Default to false 'threads' => null, // an empty value here uses processor count to determine 'subsystem' => false, // default to database, or 'stomp' - 'basename' => '/gnusocial/queue/', + 'basename' => '/queue/gnusocial/', 'control_channel' => '/topic/gnusocial/control', // broadcasts to all queue daemons 'monitor' => null, // URL to monitor ping endpoint (work in progress) - 'softlimit' => '90%', // total size or % of memory_limit at which to restart queue threads gracefully - 'spawndelay' => 1, // Wait at least N seconds between (re)spawns of child processes to avoid slamming the queue server with subscription startup + 'soft_limit' => '90%', // total size or % of memory_limit at which to restart queue threads gracefully + 'spawn_delay' => 1, // Wait at least N seconds between (re)spawns of child processes to avoid slamming the queue server with subscription startup 'debug_memory' => false, // true to spit memory usage to log 'stomp_server' => null, 'stomp_username' => null, @@ -92,92 +90,24 @@ abstract class DefaultSettings 'max_retries' => 10, // drop messages after N failed attempts to process (Stomp) 'dead_letter_dir' => false, // set to directory to save dropped messages into (Stomp) ], - 'license' => - ['type' => 'cc', // can be 'cc', 'allrightsreserved', 'private' - 'owner' => null, // can be name of content owner e.g. for enterprise - 'url' => 'https://creativecommons.org/licenses/by/3.0/', - 'title' => 'Creative Commons Attribution 3.0', - 'image' => '/theme/licenses/cc_by_3.0_80x15.png', - ], - 'mail' => - ['backend' => 'mail', - 'params' => null, - 'domain_check' => true, - ], - 'nickname' => - ['blacklist' => [], - 'featured' => [], - ], - 'profile' => - ['banned' => [], - 'bio_text_limit' => null, - 'allow_change_nick' => false, - 'allow_private_stream' => false, // whether to allow setting stream to private ("only followers can read") - 'backup' => false, // can cause DoS, so should be done via CLI - 'restore' => false, - 'delete' => false, - 'move' => false, - ], - 'image' => ['jpegquality' => 85], 'avatar' => ['server' => null, - 'dir' => INSTALLDIR . '/file/avatar/', 'url_base' => '/avatar/', 'ssl' => null, - 'max_px_size' => 300, + 'dir' => INSTALLDIR . '/file/avatar/', + 'max_size_px' => 300, ], - 'foaf' => ['mbox_sha1sum' => false], - 'public' => - ['local_only' => false, - 'blacklist' => [], - 'exclude_sources' => [], - ], - 'theme_upload' => ['enabled' => extension_loaded('zip')], - 'javascript' => - ['server' => null, - 'url_base' => null, - 'ssl' => null, - 'bustframes' => true, + 'javascript' => + ['server' => null, + 'url_base' => '/js/', + 'ssl' => null, + 'bust_frames' => true, ], - 'throttle' => - ['enabled' => true, // whether to throttle posting dents - 'count' => 20, // number of allowed messages in timespan - 'timespan' => 600, // timespan for throttling - ], - 'invite' => ['enabled' => true], - 'tag' => - ['dropoff' => 864000.0, // controls weighting based on age - 'cutoff' => 86400 * 90, // only look at notices posted in last 90 days - ], - 'popular' => - ['dropoff' => 864000.0, // controls weighting based on age - 'cutoff' => 86400 * 90, // only look at notices favorited in last 90 days - ], - 'daemon' => - ['piddir' => sys_get_temp_dir(), - 'user' => false, - 'group' => false, - ], - 'email_post' => ['enabled' => false], - 'sms' => ['enabled' => false], - 'ping' => - ['notify' => [], - 'timeout' => 2, - ], - 'new_users' => - ['default_subscriptions' => null, - 'welcome_user' => null, - ], - 'linkify' => // "bare" below means "without schema", like domain.com vs. https://domain.com - ['bare_domains' => false, // convert domain.com to domain.com ? - 'bare_ipv4' => false, // convert IPv4 addresses to hyperlinks? - 'bare_ipv6' => false, // convert IPv6 addresses to hyperlinks? - ], 'attachments' => - ['server' => null, - 'dir' => INSTALLDIR . '/file/', - 'url_base' => '/file/', - 'ssl' => null, + ['server' => null, + 'url_base' => '/file/', + 'ssl' => null, + 'dir' => INSTALLDIR . '/file/uploads/', 'supported' => ['application/vnd.oasis.opendocument.chart' => 'odc', 'application/vnd.oasis.opendocument.formula' => 'odf', @@ -222,77 +152,144 @@ abstract class DefaultSettings 'show_thumbs' => true, // show thumbnails in notice lists for uploaded images, and photos and videos linked remotely that provide oEmbed info 'process_links' => true, // check linked resources for embeddable photos and videos; this will hit referenced external web sites when processing new messages. 'ext_blacklist' => [], + 'filename' => 'hash', 'memory_limit' => '1024M', // PHP memory limit to use temporarily when handling images ], 'thumbnail' => - ['dir' => INSTALLDIR . '/file/thumbnails/', // falls back to File::path('thumb') (equivalent to ['attachments']['dir'] . '/thumb/') - 'url_base' => null, // falls back to generating a URL with File::url('thumb/$filename') (equivalent to ['attachments']['path'] . '/thumb/') - 'server' => null, // Only used if ['thumbnail']['path'] is NOT empty, and then it falls back to ['site']['server'], schema is decided from GNUsocial::useHTTPS() + ['server' => null, + 'url_base' => '/thumb/', + 'ssl' => null, + 'dir' => INSTALLDIR . '/file/thumbnails/', // falls back to File::path('thumb') (equivalent to ['attachments']['dir'] . '/thumb/') 'crop' => false, // overridden to true if thumb height === null - 'max_px_size' => 1000, // thumbs with an edge larger than this will not be generated + 'max_size_px' => 1000, // thumbs with an edge larger than this will not be generated 'width' => 450, 'height' => 600, 'upscale' => false, 'animated' => false, // null="UseFileAsThumbnail", false="can use still frame". true="allow animated" ], + 'theme' => + ['server' => null, + 'url_base' => '/theme/', + 'ssl' => null, + 'dir' => INSTALLDIR . '/public/theme/' + ], + 'plugins' => + ['server' => null, + 'url_base' => null, + 'ssl' => null, + 'core' => [], + 'default' => [], + 'locale_path' => null, // Set to a path to use *instead of* each plugin's own locale subdirectories + ], + 'license' => + ['type' => 'cc', // can be 'cc', 'allrightsreserved', 'private' + 'owner' => null, // can be name of content owner e.g. for enterprise + 'url' => 'https://creativecommons.org/licenses/by/4.0/', + 'title' => 'Creative Commons Attribution 4.0', + 'image' => '/theme/licenses/cc_by_4.0.png', + ], + 'mail' => + ['backend' => 'mail', + 'params' => null, + 'domain_check' => true, + ], + 'nickname' => + ['blacklist' => ['doc', 'main', 'avatar', 'theme'], + 'featured' => [], + ], + 'profile' => + ['banned' => [], + 'bio_text_limit' => null, + 'allow_nick_change' => false, + 'allow_private_stream' => true, // whether to allow setting stream to private ("only followers can read") + 'backup' => false, // can cause DoS, so should be done via CLI + 'restore' => false, + 'delete' => false, + 'move' => false, + ], + 'image' => ['jpegquality' => 85], + 'theme_upload' => + ['enabled' => true, + 'formats' => ['zip', 'tar', 'gz', 'tar.gz']], + 'foaf' => ['mbox_sha1sum' => false], + 'public' => + ['local_only' => false, + 'blacklist' => [], + 'exclude_sources' => [], + ], + 'throttle' => + ['enabled' => true, // whether to throttle posting dents + 'count' => 20, // number of allowed messages in timespan + 'timespan' => 600, // timespan for throttling + ], + 'invite' => ['enabled' => true], + 'tag' => + ['dropoff' => 86400 * 10, // controls weighting based on age + 'cutoff' => 86400 * 90, // only look at notices posted in last 90 days + ], + 'popular' => + ['dropoff' => 86400 * 10, // controls weighting based on age + 'cutoff' => 86400 * 90, // only look at notices favorited in last 90 days + ], + 'daemon' => + ['piddir' => sys_get_temp_dir(), + 'user' => false, + 'group' => false, + ], + 'ping' => + ['notify' => [], + 'timeout' => 2, + ], + 'new_users' => + ['default_subscriptions' => null, + 'welcome_user' => null, + ], + 'linkify' => // "bare" below means "without schema", like domain.com vs. https://domain.com + ['bare_domains' => false, // convert domain.com to domain.com ? + 'linkify_ipv4' => false, // convert IPv4 addresses to hyperlinks? + 'linkify_ipv6' => false, // convert IPv6 addresses to hyperlinks? + ], 'group' => ['max_aliases' => 3, 'description_limit' => null, - 'auto_add_tag' => true, ], 'people_tag' => ['max_tags' => 100, // maximum number of tags a user can create. 'max_people' => 500, // maximum no. of people with the same tag by the same user - 'allow_tagging' => ['all' => true], // equivalent to array('local' => true, 'remote' => true) + 'allow_tagging' => ['local' => true, 'remote' => true], // equivalent to array() 'description_limit' => null, ], 'search' => ['type' => 'like'], - 'html_filter' => // remove tags from user/remotely generated HTML if they are === true - ['img' => true, - 'video' => true, - 'audio' => true, - 'script' => true, - ], + 'html_filter' => ['tags' => ['img', 'video', 'audio', 'script']], 'notice' => ['content_limit' => null, 'allow_private' => false, // whether to allow users to "check the padlock" to publish notices available for their subscribers. - 'default_scope' => null, // null means 1 if site/private, 0 otherwise - 'hide_spam' => true, // Whether to hide silenced users from timelines + 'hide_banned' => true, // Whether to hide silenced users from timelines ], 'message' => ['content_limit' => null], - 'location' => - ['share' => 'user', // whether to share location; 'always', 'user', 'never' - 'share_default' => false, ], - 'plugins' => - ['core' => [], - 'default' => [], - 'locale_path' => false, // Set to a path to use *instead of* each plugin's own locale subdirectories - 'server' => null, - 'url_base' => null, - ], + 'location' => ['share' => 'user'], 'admin' => ['panels' => ['site', 'user', 'paths', 'access', 'sessions', 'sitenotice', 'license', 'plugins']], 'single_user' => - ['enabled' => $_ENV['SOCIAL_SITE_PROFILE'] == 'single_user', + ['enabled' => $_ENV['SOCIAL_SITE_PROFILE'] ?? '' == 'single_user', 'nickname' => null, ], 'robots_txt' => ['crawl_delay' => 0, 'disallow' => ['main', 'settings', 'admin', 'search', 'message'], ], - 'api' => ['realm' => null], 'nofollow' => ['subscribers' => true, 'members' => true, 'peopletag' => true, 'external' => 'sometimes', // Options: 'sometimes', 'never', default = 'sometimes' ], - 'url' => - ['shortener' => 'internal', + 'url_shortener' => + ['service' => 'internal', 'max_url_length' => 100, - 'max_notice_length' => -1, + 'max_notice_length' => null, ], 'http' => // HTTP client settings when contacting other sites - ['connect_timeout' => 5, + ['ssl_ca_file' => '/docker/certbot/files/live/', 'timeout' => (int) (ini_get('default_socket_timeout')), // effectively should be this by default already, but this makes it more explicitly configurable for you users .) 'proxy_host' => null, 'proxy_port' => null, @@ -300,9 +297,9 @@ abstract class DefaultSettings 'proxy_password' => null, 'proxy_auth_scheme' => null, ], - 'router' => ['cache' => true], // whether to cache the router object. Defaults to true, turn off for devel - 'discovery' => ['cors' => false], // Allow Cross-Origin Resource Sharing for service discovery (host-meta, XRD, etc.) - 'performance' => ['high' => false], // disable some features for higher performance; default false + 'discovery' => ['CORS' => false], // Allow Cross-Origin Resource Sharing for service discovery (host-meta, XRD, etc.) + 'performance' => ['high' => false], // disable some features for higher performance; default false + 'login_command' => ['enabled' => false], ]; self::loadDefaults(!$_ENV['APP_DEBUG']);