diff --git a/doc/README.md b/doc/README.md index ea4687e5ac8a..72beb2c68f20 100644 --- a/doc/README.md +++ b/doc/README.md @@ -41,3 +41,5 @@ Work in progress. * [Enabling TURN](https://github.com/jitsi/jitsi-meet/blob/master/doc/turn.md) * [Networking FAQ](https://github.com/jitsi/jitsi-meet/blob/master/doc/faq.md) * [Cloud APIs](https://github.com/jitsi/jitsi-meet/blob/master/doc/cloud-api.md) +* [Manual Installation](https://github.com/jitsi/jitsi-meet/blob/master/doc/manual-install.md) +* [Scalable Installation](https://github.com/jitsi/jitsi-meet/blob/master/doc/scalable-installation.md) diff --git a/doc/example-config-files/scalable/jicofo_config.scalable.example b/doc/example-config-files/scalable/jicofo_config.scalable.example new file mode 100644 index 000000000000..7e4c57f20fac --- /dev/null +++ b/doc/example-config-files/scalable/jicofo_config.scalable.example @@ -0,0 +1,27 @@ +# Jitsi Conference Focus settings +# sets the host name of the XMPP server +JICOFO_HOST=localhost + +# sets the XMPP domain (default: none) +JICOFO_HOSTNAME=meet.example.com + +# sets the secret used to authenticate as an XMPP component +JICOFO_SECRET=$JICOFO_SECRET + +# sets the port to use for the XMPP component connection +JICOFO_PORT=5347 + +# sets the XMPP domain name to use for XMPP user logins +JICOFO_AUTH_DOMAIN=auth.meet.example.com + +# sets the username to use for XMPP user logins +JICOFO_AUTH_USER=focus + +# sets the password to use for XMPP user logins +JICOFO_AUTH_PASSWORD=$JICOFO_PASSWORD + +# extra options to pass to the jicofo daemon +JICOFO_OPTS="" + +# adds java system props that are passed to jicofo (default are for home and logging config file) +JAVA_SYS_PROPS="-Dnet.java.sip.communicator.SC_HOME_DIR_LOCATION=/etc/jitsi -Dnet.java.sip.communicator.SC_HOME_DIR_NAME=jicofo -Dnet.java.sip.communicator.SC_LOG_DIR_LOCATION=/var/log/jitsi -Djava.util.logging.config.file=/etc/jitsi/jicofo/logging.properties" diff --git a/doc/example-config-files/scalable/jicofo_sip-communicator.properties.scalable.example b/doc/example-config-files/scalable/jicofo_sip-communicator.properties.scalable.example new file mode 100644 index 000000000000..1757569ba673 --- /dev/null +++ b/doc/example-config-files/scalable/jicofo_sip-communicator.properties.scalable.example @@ -0,0 +1,6 @@ + +org.jitsi.jicofo.BRIDGE_MUC=JvbBrewery@internal.auth.meet.example.com +org.jitsi.jicofo.ALWAYS_TRUST_MODE_ENABLED=true + +org.jitsi.jicofo.jibri.BREWERY=JibriBrewery@internal.auth.meet.example.com +org.jitsi.jicofo.jibri.PENDING_TIMEOUT=90 diff --git a/doc/example-config-files/scalable/meet.example.com.cfg.lua.scalable.example b/doc/example-config-files/scalable/meet.example.com.cfg.lua.scalable.example new file mode 100644 index 000000000000..1a9616781b88 --- /dev/null +++ b/doc/example-config-files/scalable/meet.example.com.cfg.lua.scalable.example @@ -0,0 +1,88 @@ +plugin_paths = { "/usr/share/jitsi-meet/prosody-plugins/" } + +-- domain mapper options, must at least have domain base set to use the mapper +muc_mapper_domain_base = "meet.example.com"; + +turncredentials_secret = "turncredentials_secret_test"; + +turncredentials = { + { type = "stun", host = "meet.example.com", port = "443" }, + { type = "turn", host = "meet.example.com", port = "443", transport = "udp" }, + { type = "turns", host = "meet.example.com", port = "443", transport = "tcp" } +}; + +cross_domain_bosh = false; +consider_bosh_secure = true; + +VirtualHost "meet.example.com" + -- enabled = false -- Remove this line to enable this host + authentication = "anonymous" + -- Properties below are modified by jitsi-meet-tokens package config + -- and authentication above is switched to "token" + --app_id="example_app_id" + --app_secret="example_app_secret" + -- Assign this host a certificate for TLS, otherwise it would use the one + -- set in the global section (if any). + -- Note that old-style SSL on port 5223 only supports one certificate, and will always + -- use the global one. + ssl = { + key = "/etc/prosody/certs/meet.example.com.key"; + certificate = "/etc/prosody/certs/meet.example.com.crt"; + } + speakerstats_component = "speakerstats.meet.example.com" + conference_duration_component = "conferenceduration.meet.example.com" + -- we need bosh + modules_enabled = { + "bosh"; + "pubsub"; + "ping"; -- Enable mod_ping + "speakerstats"; + "turncredentials"; + "conference_duration"; + } + c2s_require_encryption = false + +Component "conference.meet.example.com" "muc" + storage = "memory" + modules_enabled = { + "muc_meeting_id"; + "muc_domain_mapper"; + -- "token_verification"; + } + admins = { "focus@auth.meet.example.com" } + muc_room_locking = false + muc_room_default_public_jids = true + +-- internal muc component +-- Note: This is also used from jibris +Component "internal.auth.meet.example.com" "muc" + storage = "memory" + modules_enabled = { + "ping"; + } + admins = { "focus@auth.meet.example.com", "jvb@auth.meet.example.com" } + +VirtualHost "auth.meet.example.com" + ssl = { + key = "/etc/prosody/certs/auth.meet.example.com.key"; + certificate = "/etc/prosody/certs/auth.meet.example.com.crt"; + } + authentication = "internal_plain" + +Component "focus.meet.example.com" + component_secret = "jicofo_secret_test" + +Component "speakerstats.meet.example.com" "speakerstats_component" + muc_component = "conference.meet.example.com" + + +Component "conferenceduration.meet.example.com" "conference_duration_component" + muc_component = "conference.meet.example.com" + +-- for Jibri +VirtualHost "recorder.meet.example.com" + modules_enabled = { + "ping"; + } + authentication = "internal_plain" + c2s_require_encryption = false diff --git a/doc/example-config-files/scalable/prosody.cfg.lua.scalable.example b/doc/example-config-files/scalable/prosody.cfg.lua.scalable.example new file mode 100644 index 000000000000..698f522d4a71 --- /dev/null +++ b/doc/example-config-files/scalable/prosody.cfg.lua.scalable.example @@ -0,0 +1,114 @@ +-- Prosody XMPP Server Configuration + +---------- Server-wide settings ---------- +-- Settings in this section apply to the whole server and are the default settings +-- for any virtual hosts + +admins = { } + +network_backend = "epoll" + +-- This is the list of modules Prosody will load on startup. +-- It looks for mod_modulename.lua in the plugins folder, so make sure that exists too. +-- Documentation for bundled modules can be found at: https://prosody.im/doc/modules +modules_enabled = { + + -- Generally required + "roster"; -- Allow users to have a roster. Recommended ;) + "saslauth"; -- Authentication for clients and servers. Recommended if you want to log in. + "tls"; -- Add support for secure TLS on c2s/s2s connections + "dialback"; -- s2s dialback support + "disco"; -- Service discovery + + -- Not essential, but recommended + "carbons"; -- Keep multiple clients in sync + "pep"; -- Enables users to publish their avatar, mood, activity, playing music and more + "private"; -- Private XML storage (for room bookmarks, etc.) + "blocklist"; -- Allow users to block communications with other users + "vcard4"; -- User profiles (stored in PEP) + "vcard_legacy"; -- Conversion between legacy vCard and PEP Avatar, vcard + + -- Nice to have + "version"; -- Replies to server version requests + "uptime"; -- Report how long server has been running + "time"; -- Let others know the time here on this server + "ping"; -- Replies to XMPP pings with pongs + "register"; -- Allow users to register on this server using a client and change passwords + --"mam"; -- Store messages in an archive and allow users to access it + --"csi_simple"; -- Simple Mobile optimizations + + -- Admin interfaces + "admin_adhoc"; -- Allows administration via an XMPP client that supports ad-hoc commands + --"admin_telnet"; -- Opens telnet console interface on localhost port 5582 + + -- HTTP modules + --"bosh"; -- Enable BOSH clients, aka "Jabber over HTTP" + --"websocket"; -- XMPP over WebSockets + --"http_files"; -- Serve static files from a directory over HTTP + + -- Other specific functionality + --"limits"; -- Enable bandwidth limiting for XMPP connections + --"groups"; -- Shared roster support + --"server_contact_info"; -- Publish contact information for this service + --"announce"; -- Send announcement to all online users + --"welcome"; -- Welcome users who register accounts + --"watchregistrations"; -- Alert admins of registrations + --"motd"; -- Send a message to users when they log in + --"legacyauth"; -- Legacy authentication. Only used by some old clients and bots. + --"proxy65"; -- Enables a file transfer proxy service which clients behind NAT can use +} + +-- These modules are auto-loaded, but should you want +-- to disable them then uncomment them here: +modules_disabled = { + -- "offline"; -- Store offline messages + -- "c2s"; -- Handle client connections + -- "s2s"; -- Handle server-to-server connections + -- "posix"; -- POSIX functionality, sends server to background, enables syslog, etc. +} + +-- Disable account creation by default, for security +-- For more information see https://prosody.im/doc/creating_accounts +allow_registration = false + +-- Force clients to use encrypted connections? This option will +-- prevent clients from authenticating unless they are using encryption. + +c2s_require_encryption = true + +-- Force servers to use encrypted connections? This option will +-- prevent servers from authenticating unless they are using encryption. + +s2s_require_encryption = true + +-- Force certificate authentication for server-to-server connections? + +s2s_secure_auth = false + + +-- Required for init scripts and prosodyctl +pidfile = "/var/run/prosody/prosody.pid" + +-- Select the authentication backend to use. The 'internal' providers +-- use Prosody's configured data storage to store the authentication data. + +authentication = "internal_hashed" + +archive_expires_after = "1w" -- Remove archived messages after 1 week + +-- Logging configuration +-- For advanced logging see https://prosody.im/doc/logging +log = { + info = "/var/log/prosody/prosody.log"; -- Change 'info' to 'debug' for verbose logging + error = "/var/log/prosody/prosody.err"; + -- "*syslog"; -- Uncomment this for logging to syslog + -- "*console"; -- Log to the console, useful for debugging with daemonize=false +} + + +-- Location of directory to find certificates in (relative to main config file): +certificates = "certs" + +VirtualHost "localhost" + +Include "conf.d/*.cfg.lua" diff --git a/doc/example-config-files/scalable/videobridge_config.scalable.example b/doc/example-config-files/scalable/videobridge_config.scalable.example new file mode 100644 index 000000000000..bc33341e026a --- /dev/null +++ b/doc/example-config-files/scalable/videobridge_config.scalable.example @@ -0,0 +1,20 @@ +# Jitsi Videobridge settings + +# sets the XMPP domain (default: none) +JVB_HOSTNAME=meet.example.com + +# sets the hostname of the XMPP server (default: domain if set, localhost otherwise) +JVB_HOST= + +# sets the port of the XMPP server (default: 5275) +JVB_PORT=5347 + +# sets the shared secret used to authenticate to the XMPP server +JVB_SECRET=$VP_SECRET + +# extra options to pass to the JVB daemon +JVB_OPTS="--apis=rest," + + +# adds java system props that are passed to jvb (default are for home and logging config file) +JAVA_SYS_PROPS="-Dnet.java.sip.communicator.SC_HOME_DIR_LOCATION=/etc/jitsi -Dnet.java.sip.communicator.SC_HOME_DIR_NAME=videobridge -Dnet.java.sip.communicator.SC_LOG_DIR_LOCATION=/var/log/jitsi -Djava.util.logging.config.file=/etc/jitsi/videobridge/logging.properties" diff --git a/doc/example-config-files/scalable/videobridge_sip-communicator.properties.scalable.example b/doc/example-config-files/scalable/videobridge_sip-communicator.properties.scalable.example new file mode 100644 index 000000000000..048acd356db4 --- /dev/null +++ b/doc/example-config-files/scalable/videobridge_sip-communicator.properties.scalable.example @@ -0,0 +1,19 @@ +org.ice4j.ice.harvest.DISABLE_AWS_HARVESTER=true +org.ice4j.ice.harvest.STUN_MAPPING_HARVESTER_ADDRESSES=meet-jit-si-turnrelay.jitsi.net:443 + +org.jitsi.jicofo.ALWAYS_TRUST_MODE_ENABLED=true + +org.jitsi.videobridge.ENABLE_REST_SHUTDOWN=true + +# Enable broadcasting stats/presence in a MUC +org.jitsi.videobridge.ENABLE_STATISTICS=true +org.jitsi.videobridge.STATISTICS_TRANSPORT=muc,colibri,rest +org.jitsi.videobridge.STATISTICS_INTERVAL=5000 + +org.jitsi.videobridge.xmpp.user.shard-1.HOSTNAME=meet.example.com +org.jitsi.videobridge.xmpp.user.shard-1.DOMAIN=auth.meet.example.com +org.jitsi.videobridge.xmpp.user.shard-1.USERNAME=jvb +org.jitsi.videobridge.xmpp.user.shard-1.PASSWORD=$VB_PASSWORD +org.jitsi.videobridge.xmpp.user.shard-1.MUC_JIDS=JvbBrewery@internal.auth.meet.example.com +org.jitsi.videobridge.xmpp.user.shard-1.MUC_NICKNAME=$NICKNAME_OF_VB +org.jitsi.videobridge.xmpp.user.shard-1.DISABLE_CERTIFICATE_VERIFICATION=true diff --git a/doc/manual-install.md b/doc/manual-install.md index 7163e722186e..2aa63d5ae513 100644 --- a/doc/manual-install.md +++ b/doc/manual-install.md @@ -8,6 +8,8 @@ change references to that to match your host, and generate some passwords for There are also some complete [example config files](https://github.com/jitsi/jitsi-meet/tree/master/doc/example-config-files/) available, mentioned in each section. +There are additional configurations to be done for a [scalable installation](https://github.com/jitsi/jitsi-meet/tree/master/doc/scalable-installation.md) + ## Network description This is how the network looks: diff --git a/doc/scalable-installation.md b/doc/scalable-installation.md new file mode 100644 index 000000000000..26d17d408338 --- /dev/null +++ b/doc/scalable-installation.md @@ -0,0 +1,166 @@ +# Scalable Jitsi installation + +A single server Jitsi installation is good for a limited size of concurrent conferences. +The first limiting factor is the videobridge component, that handles the actual video and audio traffic. +It is easy to scale the video bridges horizontally by adding as many as needed. +In a cloud based environment, additionally the bridges can be scaled up or down as needed. + +*NB*: The [Youtube Tutorial on Scaling](https://www.youtube.com/watch?v=LyGV4uW8km8) is outdated and describes an old configuration method. + +*NB*: Building a scalable infrastructure is not a task for beginning Jitsi Administrators. +The instructions assume that you have installed a single node version successfully, and that +you are comfortable installing, configuring and debugging Linux software. +This is not a step-by-step guide, but will show you, which packages to install and which +configurations to change. Use the [manual install](https://github.com/jitsi/jitsi-meet/blob/master/doc/manual-install.md) for +details on how to setup Jitsi on a single host. +It is highly recommended to use configuration management tools like Ansible or Puppet to manage the +installation and configuration. + +## Architecture (Single Jitsi-Meet, multiple videobridges) + +A first step is to split the functions of the central jitsi-meet instance (with nginx, prosody and jicofo) and +videobridges. + +A simplified diagram (with open network ports) of an installation with one Jitsi-Meet instance and three +videobridges that are load balanced looks as follows. Each box is a server/VM. + +``` + + + + | | + | | + v v + 80, 443 TCP 443 TCP, 10000 UDP + +--------------+ +---------------------+ + | nginx | 5222, 5347 TCP | | + | jitsi-meet |<-------------------+| jitsi-videobridge | + | prosody | | | | + | jicofo | | +---------------------+ + +--------------+ | + | +---------------------+ + | | | + +----------+| jitsi-videobridge | + | | | + | +---------------------+ + | + | +---------------------+ + | | | + +----------+| jitsi-videobridge | + | | + +---------------------+ +``` + +## Machine Sizing + +The Jitsi-Meet server will generally not have that much load (unless you have many) conferences +going at the same time. A 4 CPU, 8 GB machine will probably be fine. + +The videobridges will have more load. 4 or 8 CPU with 8 GB RAM seems to be a good configuration. + + +### Installation of Jitsi-Meet + +Assuming that the installation will run under the following FQDN: `meet.example.com` and you have +SSL cert and key in `/etc/ssl/meet.example.com.{crt,key}` + +Set the following DebConf variables prior to installing the packages. +(We are not installing the `jitsi-meet` package which would handle that for us) + +Install the `debconf-utils` package + +``` +$ cat << EOF | sudo debconf-set-selections +jitsi-videobridge jitsi-videobridge/jvb-hostname string meet.example.com +jitsi-meet jitsi-meet/jvb-serve boolean false +jitsi-meet-prosody jitsi-videobridge/jvb-hostname string meet.example.com +jitsi-meet-web-config jitsi-meet/cert-choice select I want to use my own certificate +jitsi-meet-web-config jitsi-meet/cert-path-crt string /etc/ssl/meet.example.com.crt +jitsi-meet-web-config jitsi-meet/cert-path-key string /etc/ssl/meet.example.com.key +EOF +``` + +On the jitsi-meet server, install the following packages: + +* `nginx` +* `prosody` +* `jicofo` +* `jitsi-meet-web` +* `jitsi-meet-prosody` +* `jitsi-meet-web-config` + +### Installation of Videobridge(s) + +For simplicities sake, set the same `debconf` variables as above and install + +* `jitsi-videobridge2` + +### Configuration of jitsi-meet + +#### Firewall + +Open the following ports: + +Open to world: + +* 80 TCP +* 443 TCP + +Open to the videobridges only + +* 5222 TCP (for Prosody) +* 5437 TCP (for Jicofo) + + +#### NGINX + +Create the `/etc/nginx/sites-available/meet.example.com.conf` as usual + +#### Prosody + +Follow the steps in the [manual install](https://github.com/jitsi/jitsi-meet/blob/master/doc/manual-install.md) for setup tasks + +You will need to adapt the following files (see the files in `example-config-files/scalable`) + +* `/etc/prosody/prosody.cfg.lua` +* `/etc/prosody/conf.avail/meet.example.com.cfg.lua` + +#### Jitsi-Meet + +Adapt `/usr/share/jitsi-meet/config.js` and `/usr/share/jitsi-meet/interface-config.js` to your specific needs + +#### Jicofo + +You will need to adapt the following files (see the files in `example-config-files/scalable`) + +* `/etc/jitsi/jicofo/config` (hostname, jicofo_secret, jicofo_password) +* `/etc/jitsi/jicofo/sip-communicator.properties` (hostname) + +### Configuration of the Videobridge + +#### Firewall + +Open the following ports: + +Open to world: + +* 443 TCP +* 10000 UDP + +#### jitsi-videobridge2 + +You will need to adapt the following files (see the files in `example-config-files/scalable`) + +Each videobridge will have to have it's own, unique nickname + +* `/etc/jitsi/videobridge/config` (hostname, password) +* `/etc/jitsi/jicofo/sip-communicator.properties` (hostname of jitsi-meet, nickname of videobridge, vb_password) + +With the latest stable (April 2020) videobridge, it is no longer necessary to set public and private IP +adresses in the `sip-communicator.properties` as the bridge will figure out the correct configuration by itself. + +## Testing + +After restarting all services (`prosody`, `jicofo` and all the `jitsi-videobridge2`) you can see in +`/var/log/prosody/prosody.log` and +`/var/log/jitsi/jicofo.log` that the videobridges connect to Prososy and that Jicofo picks them up. + +When a new conference starts, Jicofo picks a videobridge and schedules the conference on it.