Commit abd3a47e authored by Francesc Guasch's avatar Francesc Guasch
Browse files

Merge branch 'gh-pages' into Improve-doc-cluster_1367

parents 10077e60 b0dd322f
......@@ -32,3 +32,20 @@ html_theme_options = {
html_static_path = []
html_logo = 'docs/../../img/logo_ravada.png'
# Couldn't find a way to retrieve variables nor do advanced string
# concat from reST, so had to hardcode this in the "epilog" added to
# all pages. This is used in index.rst to display the Weblate badge.
# On English pages, the badge points to the language-neutral engage page.
rst_epilog = """
.. |weblate_widget| image:: https://hosted.weblate.org/widgets/ravada/-/287x66-white.png
:alt: Translation status
:target: https://hosted.weblate.org/engage/ravada/
:width: 287
:height: 66
.. |weblate2_widget| image:: https://hosted.weblate.org/widgets/ravada/-/multi-auto.svg
:alt: Translation status
:target: https://hosted.weblate.org/engage/ravada/
:width: 400
:height: 285
""".format()
......@@ -7,7 +7,7 @@ If you want to add a new grant, you have to do two things:
- Add the condition
You can see all the grants in the table 'grants_type', to add it automatically on start up the
backend you have to modify the functions ``_add_grants`` and `` _enable_grants`` in the file "lib/Ravada.pm"
backend you have to modify the functions ``_add_grants`` and ``_enable_grants`` in the file *lib/Ravada.pm*.
Now the test file is like this:
......@@ -42,15 +42,34 @@ Now the test file is like this:
,'start_many'
);
...
Next for adding the conditions it depends of the situations but you may want to lock in to thins functions:
Next for adding the conditions it depends of the situations but you may want to look into these files:
- "templates/main/settings_machine_tabs_head.html.ep" & "templates/main/settings_machine_tabs_head.html.ep" for Virtual Machine edit settings web page.
- "lib/Ravada/Auth/SQL.pm" all the grants conditions created (i.e. ``is_admin``, ``can_list_clones``, etc...).
**Note**:If the function is named ``can_'grant_name'`` this function is automatically generated with the BD data.
**Note**: The functions like ``can_'grant_name'`` are not individually implemented. This function is automatically generated with the BD data. Its code is at *lib/Ravada/Auth/SQL.pm* ``sub AUTOLOAD``.
Grant user permissions by default
---------------------------------
At *lib/Ravada/Auth/SQL*, the sub *grant_user_permissions* sets the default for new
users. If the new permission should be for everybody, add it there too.
Defaults and upgrading
----------------------
*This sections requires some review, please contribute if you can*
Some permissions are granted by default to all the users. So when creating
a new grant you should check:
- Old users are granted the new permissions
- Newly created users get the permission too
- Admin users get the permision, both old and new
Testing
-------
Some examples for testing can be found in "/t/user/50_admin.t" and "/t/user/40_grant_shutdown.t" also you may want to read the section **How to create tests**.
Some examples for testing can be found in */t/user/50_admin.t* and */t/user/40_grant_shutdown.t* also you may want to read the section **How to create tests**.
......@@ -92,7 +92,12 @@ Changelog file:
$ gvim Changelog.md
$ git commit -a
Push changes
------------
::
$ git push
Close the release
-----------------
......
......@@ -16,7 +16,7 @@ source code:
.. prompt:: bash ~/src/ravada$
PERL5LIB=./lib morbo ./script/rvd_front
PERL5LIB=./lib morbo -m development -v ./script/rvd_front
The backend runs as root because it has to deal with the VM processes.
It won't reload automatically when there is a change, so it has to be
......@@ -44,7 +44,7 @@ If you use the fish shell you must run the scripts with these commands:
.. prompt:: bash ~/src/ravada$
set -x PERL5LIB ./lib ; morbo -v script/rvd_front
set -x PERL5LIB ./lib ; morbo -m development -v script/rvd_front
.. prompt:: bash ~/src/ravada$
......
......@@ -21,4 +21,67 @@ Run a single test
.. prompt:: bash $
make; sudo prove -b t/lxc/*t
make; sudo prove -l t/lxc/\*t
Advanced Features tests
-----------------------
LDAP
~~~~
Install a `local LDP server <http://ravada.readthedocs.io/en/latest/docs/ldap_local.html>`_
to run the LDAP tests.
Nodes
~~~~~
Install two virtual machines called ztest-1 and ztest-2 with these features:
- OS: Lubuntu 18.04
- Disk Size: 20 GB
- RAM : At least 4 GB
Follow the remote nodes configuration guide so those machines can be accessed
from root in the test host. Also, KVM virtual packages are required. The easiest
way is install a virtual machine and clone it twice.
Both machines must answer to two IPs as defined in the configurationa.
Place in t/etc/remote_vm.conf this config file:
::
ztest-1:
vm:
- KVM
- Void
host: 192.168.122.151
public_ip: 192.168.122.251
ztest-2:
vm:
- KVM
- Void
host: 192.168.122.152
public_ip: 192.168.122.252
Base Test machine
~~~~~~~~~~~~~~~~~~
Create a small virtual machine called z-test-base:
- OS: Debian Stretch 64 Bits
- Disk: size: 6 GB
- RAM: 1 GB
Configure the `Set Hostname <http://ravada.readthedocs.io/en/latest/docs/set_hostname.html>`_
so it gets automatically changed on statup.
You can remove office packages and trim it down with virt-sparsify.
Install openssh-server in base.
Allow root user from host test machine password-less ssh to the PCs.
When everything is set up prepare this machine as a base. When it is done you can run
the tests and it will be used to create clones and check stuff on it.
Translations
============
Localization and translation
============================
We use `Transifex <https://www.transifex.com/ravada/ravada/>`__ to
provide a cleaner and easy to use interface for translators.
.. centered:: |weblate2_widget|
New entries must be added in the ``en.po`` file.
Because it is the basis of the other language files.
You can translate Ravada at `Weblate <https://hosted.weblate.org/engage/ravada/>`__. As a feature rich computer aided translation tool, Weblate saves both developers and translators time.
.. Warning:: Please don't add new entries in other .po files directly. Use `Transifex <https://www.transifex.com/ravada/ravada/>`__ instead. If you want to collaborate, create an `Issue <https://github.com/UPC/ravada/issues/new>`_ and give you access as a translator of the language you want.
.. centered:: |weblate_widget|
.. image:: ../../img/translate.png
- Automated localization workflow
- Quality checks
- Attribution, all translator are properly credited
You can read weblate feaures `here <https://hosted.weblate.org/projects/ravada/#languages>`_.
Ravada weblate repository is updated from Github, and the contributions goes automatic to develop branch in Github.
New entries
-----------
New english entries must be added in the ``en.po`` file. It's the origin of the other language files. This new strings will be incorporated automatically in weblate.
.. Warning:: Please don't add new entries in other .po files directly. Use `Weblate <https://hosted.weblate.org/projects/ravada/translation/>`__ instead.
The language files are stored `here <https://github.com/UPC/ravada/tree/master/lib/Ravada/I18N/>`_ in lib/Ravada/I18N.
Before uploading the changes check if there are repeated msgid.
The ``msguniq`` command should not display any output lines.
::
When creating a new translation language, also add it in the frontend so it gets
listed for the end users. At around line 1337 in the ``sub _translation`` add
a line like this:
.. code-block:: perl
$ msguniq --repeated en.po
sub _translations($c) {
my %lang_name=(
ar => 'Arab'
,en => 'English'
....
,XX => 'New language'
Ravada CLI
==========
There are some things you can do from the CLI with Ravada.
This document is a work in progress. If you are interested in documenting
more any feature `let us know <https://ravada.upc.edu/#help>`_.
Help
----
.. prompt:: bash
sudo rvd_back --help
LDAP
----
You can execute some LDAP actions from the command line.
Test LDAP connection
~~~~~~~~~~~~~~~~~~~~
If you wonder if Ravada is able to access correctly to your LDAP server
use the *--test-ldap* flag. First it will try to connect, then you can
type an username and password to confirm it is a valid user.
::
$ sudo rvd_back --test-ldap
Connection to LDAP ok
login: jimmy.mcnulty
password: whatever
LOGIN OK bind
Create LDAP user
~~~~~~~~~~~~~~~~
Add a new entry in your LDAP server. Warning the password will be shown in the
clear.
.. prompt :: bash
$ sudo rvd_back --add-user-ldap jimmy.mcnulty
Create LDAP group
~~~~~~~~~~~~~~~~~
Add a new group in your LDAP server. These are POSIX groups with member uids
inside.
.. prompt :: bash
$ sudo rvd_back --add-group-ldap staff
Add users to LDAP groups
~~~~~~~~~~~~~~~~~~~~~~~~
Once you have users and groups in your LDAP server you can easily add member entries
to a group. *Warning* : the user must have logged in at least once.
A list of known LDAP groups will be shown. If the user is already member of a group
it will be flagged with a *YES*. Type the name of the new group you want the
user to belong to:
.. prompt :: bash
$ rvd_back --add-user-group jimmy.mcnulty
- staff :
- cops : YES
- students :
- teachers :
Add user to LDAP group: teachers
Cluster Hardware
================
Shared Storage
--------------
If you are planning to build a large cluster of Ravada nodes you may
go to an expensive shared storage infraestructure. Be aware this can
be a big deployment that can give access to thousands of users, but
it will be expensive and you may have some perfomance issues.
Ravada is easy to grow, so try first a single
`Server <http://ravada.readthedocs.io/en/latest/docs/Server_Hardware.html>`_
setup and you can add more later.
Recommendations
---------------
This document needs more detailed information, for starters:
* Shared Storage with 10 GB or Fiber networking
* All Flash or mixed storage
* Two network switches for data channels
......@@ -15,7 +15,7 @@ You can also install Ravada using Docker.
Hardware
--------
It depends on the number and type of virtual machines. For common scenarios are server memory, storage and network bandwidth the most critical requirements.
It depends on the number and type of virtual machines. For common scenarios server memory, storage and network bandwidth are the most critical requirements.
Memory
~~~~~~
......@@ -31,6 +31,10 @@ Disks
The faster the disks, the better. Ravada uses incremental files for the
disks images, so clones won't require many space.
Read these
`recommendations <http://ravada.readthedocs.io/en/latest/docs/Server_Hardware.html>`_
if you want to buy a new dedicated server.
Install Ravada
--------------
......
......@@ -19,14 +19,14 @@ repository <http://infoteleco.upc.edu/img/debian/>`__.
Install the ravada package. Choose the one that matches your OS release:
- ravada_0.8.3_debian-10_all.deb
- ravada_1.0.1_debian-10_all.deb
When you run dpkg now it may show some errors, it is ok, keep reading.
.. prompt:: bash $
wget http://infoteleco.upc.edu/img/debian/ravada_0.8.3_debian-10_all.deb
sudo dpkg -i ravada_0.8.3_debian-10_all.deb
wget http://infoteleco.upc.edu/img/debian/ravada_1.0.1_debian-10_all.deb
sudo dpkg -i ravada_1.0.1_debian-10_all.deb
The last command will show a warning about missing dependencies. Install
them running:
......@@ -107,7 +107,7 @@ When asked if this user is admin answer *yes*.
.. prompt:: bash $
sudo /usr/sbin/rvd_back --add-user user.name
sudo /usr/sbin/rvd_back --add-user admin
Client
------
......
......@@ -119,7 +119,7 @@ When asked if this user is admin answer *yes*.
.. prompt:: bash $
sudo /usr/sbin/rvd_back --add-user user.name
sudo /usr/sbin/rvd_back --add-user admin
Firewall (Optional)
-------------------
......
......@@ -18,18 +18,15 @@ repository <http://infoteleco.upc.edu/img/debian/>`__.
Install the ravada package. Choose the one that matches your OS release:
- ravada_0.8.3_ubuntu-18.04_all.deb
- ravada_0.8.3_ubuntu-18.10_all.deb
- ravada_0.8.3_ubuntu-19.04_all.deb
- ravada_0.8.3_ubuntu-19.10_all.deb
- ravada_1.0.1_ubuntu-18.04_all.deb
- ravada_1.0.1_ubuntu-20.04_all.deb
When you run dpkg now it may show some errors, it is ok, keep reading.
.. prompt:: bash $
wget http://infoteleco.upc.edu/img/debian/ravada_0.8.3_ubuntu-18.04_all.deb
sudo dpkg -i ravada_0.8.3_ubuntu-18.04_all.deb
wget http://infoteleco.upc.edu/img/debian/ravada_1.0.1_ubuntu-20.04_all.deb
sudo dpkg -i ravada_1.0.1_ubuntu-20.04_all.deb
The last command will show a warning about missing dependencies. Install
them running:
......@@ -112,7 +109,7 @@ When asked if this user is admin answer *yes*.
.. prompt:: bash $
sudo /usr/sbin/rvd_back --add-user user.name
sudo /usr/sbin/rvd_back --add-user admin
Client
------
......
......@@ -81,7 +81,7 @@ Add a new user for the ravada web. Use ``rvd_back`` to create it.
.. prompt:: bash $
cd ravada
sudo PERL5LIB=./lib ./script/rvd_back --add-user user.name
sudo PERL5LIB=./lib ./script/rvd_back --add-user admin
Firewall(Optional)
......@@ -135,7 +135,7 @@ Run the frontend in another terminal:
.. prompt:: bash $
PERL5LIB=./lib morbo ./script/rvd_front
PERL5LIB=./lib morbo -m development -v ./script/rvd_front
Server available at http://127.0.0.1:3000
Now you must be able to reach ravada at the location http://your.ip:3000/
......
......@@ -51,7 +51,8 @@ Follow this steps:
cd ~
mkdir src
git clone https://github.com/UPC/ravada.git
cd src/
git clone https://github.com/UPC/ravada.git
cd ravada/dockerfy
.. prompt:: bash $
......
Kiosk Mode
==========
This feature is available since Ravada version 1.1 currently in development
due April 2021. Download it from http://infoteleco.upc.edu/img/debian/
Kiosk ( or anonymous ) allows any user, not logged in, to create a volatile
virtual machine. Once this machine is shut down, it is destroyed automatically.
......@@ -10,72 +13,61 @@ Setting
This *kiosk* mode must be defined for some bases in some networks.
.. note ::
Unfortunately kiosk mode configuration has not been added to the frontend.
Anyway it can be set only from within the database.
Follow these steps carefully.
Backup the Database
-------------------
As we are going to change the database, any mistake can be fatal. Backup before.
If you want to have the data handy do it right now:
.. prompt:: bash #
mysqldump -u root -p ravada domains > domains.sql
mysqldump -u root -p ravada networks > networks.sql
Define a Network
----------------
You can allow kiosk mode from any network, but you can define a new network where
this mode is allowed.
.. prompt:: bash #,(env)... auto
Go to Admin Tools, Networks and click *New Network*.
# mysql -u root -p ravada
mysql> insert into networks (name, address) values ('classroom','10.0.68.0/24');
.. figure:: images/new_network.jpg
:alt: New network form
New network form
Find the ids
------------
Set a name for this network definition, you may want to allow access without
client password. Enable *all machines* so users from this network can access the
virtual machines.
You must find what is the id of the network and the virtual machine where kiosk mode is enabled.
This domain must be a base and allowed public access.
::
Allow anonymous mode
--------------------
mysql> select id,name from domains where name='blablabla' and is_base=1 and is_public=1;
+----+-------------------+
| id | name |
+----+-------------------+
| 22 | blablabla |
+----+-------------------+
mysql> select id,name from networks;
+----+-----------+
| id | name |
+----+-----------+
| 1 | localnet |
| 4 | all |
| 6 | classroom |
+----+-----------+
You can allow anonymous access to some bases from the networks management form.
Go to Admin Tools, Networks and click in the name of the network. If you want to
grant anonymous users to everyone use the *default* network. This is not a good
practice unless the server is behind a firewall. Otherwise create a new network
and grant anonymous access only to the users that come from there.
Click on the button *Machines*. A list of all the bases will be shown. For a base
to be used anonymously it must be defined as public and the *anonymous* option must
be selected.
Allow anonymous mode
--------------------
In this example we configure anonymous access to the base called *focal*.
.. image:: images/network_machines.jpg
Setting a base as *public* allows any known user with access to run it. Anonymous gives
access to everyone in your network without an username.
Auto remove anonymous machines
------------------------------
::
Virtual machines created for anonymous users can be easily and automatically removed.
Go to Admin Tools, Machines, and click in the name of the base. In the *Options* tab
enter a *timeout* and optionally *shutdown disconnected*.
mysql> insert into domains_network(id_domain, id_network,anonymous) VALUES(33, 6, 1);
In this example the virtual machine will be destroyed when the user closes the viewer
or after running for 60 minutes.
.. image:: images/machine_options.jpg
Access
------
Access now to the anonymous section in your ravada web server. http://your.ip:8081/anonymous
Access now to the anonymous section in your ravada web server. http://your.server.com/anonymous
You should see there the base of the virtual machine you allowed before.
......@@ -24,6 +24,10 @@ In this case, the Port field must be set with the RDP number:
.. image:: images/rdp-redirection.png
Yo do not need to configure the port in each Virtual Machine clone. Setting the
exposed port in the base replicates this configuration to all the clones. This works
even after the clones have been created.
Open the Virtual Machine with a RDP client
------------------------------------------
......
Keeping the Base updated
========================
Base volumes
------------
Once a base is prepared and clones are made the base becomes *read only*.
This is required because the clones disk volumes depend of the data stored
in the bases. So it is not possible to change the base because the clones
storage would become corrupted.
.. image:: images/base_clone_volumes.png
Rebasing
--------
There is a way to keep the base updated for all the clones. This require
you create a new base from the old one and make all the clones depend from
the new one. This is called *rebase* and requires careful preparation in advance.
Virtual Machine Volumes
-----------------------
Restoring clones
~~~~~~~~~~~~~~~~
Before showing the virtual machine volumes, we must explain the restore procedure.
.. image:: images/restore.png
When an user requests a *restore* of a clone. This virtual machine system
information get removed. When it starts again the original content created
in the base will show up.
This is different than removing the Virtual Machine. If it is removed all
the content and the Virtual Machine itself will be deleted. So just restored
machines still are shown in the lists.
Volume Types
~~~~~~~~~~~~
There are thre kinds of disk volumes that can be assigned to the Virtual Machines:
- System: This is the normal storage. Removed on restore.
- Temporary: Content will be cleaned on restore and shutdown
- Data: Content will be kept on restore
So you should use temporary volumes for *swap* , *pagefile* or other temporary files.
Use data volumes to store users files and other information that doesn't depend
of the operative system.
When you *rebase* a virtual machine, system volumes will be replaced and
*data volumes will be kept untouched*.
Rebase requirements
-------------------
When you rebase, the new base virtual machine must have the same storage outline
as the old base. A good practice is to clone the old base, do some changes and
make it the new base.
After the rebase procedure is completed, the operative system will be replaced,
the temporary files would be restored to their initial state and the data volumes
will be exactly like they were before rebasing.
.. image:: images/rebase.png
Run rebase on the virtual machine options at the base screen. You can rebase only
one clone or request all the clones to be updated. This will take a few minutes.