allTags Server

1. Introduction
2. System requirements
3. Installation
4. Configuration
5. Person and client management
6. Access permissions
7. Conflict management
8. Logging
9. Backup and recovery
10. Update
11. Expansion keys

Introduction

allTags Server provides central access to shared files and management of connected clients. Via defined shares and permissions, clients can retrieve and update content as well as download files for offline use.

Multiple clients are assigned to a single person to enable multi-device access to content, while permissions are set for personal or group access. Conflict resolution functions are included in case of parallel or asynchronous offline commits from multiple clients.

allTags Server is administrated via a connected allTags Client with administrative permissions. To setup allTags Server, basic system administration skills are required. The following steps include installation of the server component, setup of a database and changing of a server configuration file.

System requirements

• A current Linux or Windows server OS
  • Windows: Tested on 2012 R2 and newer.
  • Linux: Tested on modern Debian versions as well as derivates like Ubuntu Server, native and as docker container. It runs on most modern Linux server distributions with a syslog daemon.
• 1 GB RAM
• Hard disk space depending on size of managed files
• MariaDB 10 or newer

Installation

• Windows: allTags Server provides a graphical installer for Windows. Please follow the installation wizard until it has executed successfully.
• Linux: Currently there is no installation script or package available for allTags Server for Linux. Fortunately, allTags Server on Linux basically has no external dependencies. Extract the latest Linux release of allTags Server to a folder of your choice and make alltags_server executable.

Configuration

On both Windows and Linux, these steps must be completed to configure allTags Server.

Configure database

1. Connect to your MariaDB server with administrative privileges.
2. Create a new database for allTags Server. Choose a desired database name like 'alltags_server' and the collation utf8_unicode_ci.
3. Create a new database user for allTags Server. Choose a desired database user name and password and grant all rights except GRANT to the newly created database.

Configure server

Open the allTags Server configuration file config.json, located in the chosen installation directory.

• Enter your database details under database. Host refers to the server hostname of the database server running the new allTags database. Name refers to the database name itself, user and pass are the user credentials you have chosen for the database user.
• Enter the hostname with which clients can reach this allTags Server under webServer->hostname. This should be the fully qualified domain name (FQDN). It is relevant for the server certificate, which is used for encrypted communication with clients.
• Setup a firewall rule to enable access to the allTags Server port (by default 55501) for connecting clients. This port can be changed under webServer->port.
• Optionally, use a public/private server certificate by switching the configuration parameter webserver->selfSigned to false.
  • By default, a self-signed certificate will be used for encrypted communication with connected clients. Clients will know that they are communicating with the correct server by checking a server fingerprint, of which a copy will be exchanged before a client connects for the first time. The self-signed certificate will be managed automatically.
  • To further strengthen security, you can use a public/private certificate. This is very specific to your organization and your certification infrastructure (if you have one) and is not part of this documentation. If you can provide a public or private certificate for this server, it has to match the FQDN of the server, which must be the same hostname that clients attempt to connect to. You must also regularly renew this certificate and restart the allTags Server service afterwards.
  • It is possible to switch from self-signed to a public/private certificate later. This however requires reconnecting clients or updating all client server settings.
• Optionally, overwrite the default storage directories for allTags Server files under paths. You can choose any accessible path, including network shares.
  • The files directory grows with the amount of files that clients share.
  • The temp directory is used for temporary file operations and is emptied regularly by allTags Server.
  • The thumbnails directory grows with shared files but much less so than files. Thumbnails are not regularly retrieved but instead synchronized to clients for local access.
  • The keys directory contains any expansion keys that you want to add to allTags Server.

Server initialization

Start the allTags Server command line interface (CLI) by executing alltags_server.exe (Windows) or alltags_server (Linux). Execute the following steps inside the CLI.

1. Select Test database connection. This will confirm whether the database connection works and the database itself is ready for initial setup.
   • Should this test fail, check your database configuration and the allTags Server configuration file. Make sure that the database server is reachable from the allTags Server and that corresponding ports (usually just 3306) are open.
2. Select Initialize empty database to populate the new allTags Server database.
3. Lastly, to connect to the new allTags Server, one administrative user and associated client must be created. Select Create new admin user... and enter details of the first user to connect to this server. After entering all details, make sure to copy the generated connection string as you will need it soon.

Service registration

Once the server has been configured, it should be registered as a proper service. Open the CLI with administrative rights and select Service: Install - this will register allTags Server as a service with your operating system.

• For testing purposes, you can also run the service from within the CLI by selecting Run server in this shell. It will then run as long as the CLI is running.

To continue, start the allTags Server service either from the allTags Server CLI or from your operating system´s service manager as such:

• Windows Server with desktop experience: services.msc, locate and start alltags_server
• Windows Server Core: Start-Service -name alltags_server
• Linux, systemd: systemctl start alltags_server
• Linux, init.d: service alltags_server start

Connect as administrator

To administrate your allTags Server, you need an allTags Client with administrative permissions. Startup an allTags client, go to settings->servers and select Add server. Here you are prompted for the connection string, which you have created during the server configuration process (s. above).

As soon as the connection has been established, you can access administrative functions via settings->servers. You might want to setup at least one additional administrative user in case the first one is not available. Should you loose all administrative access, you can create a new administrative user via the allTags Server CLI.

Person and client management

allTags differentiates between people and clients. A person is a natural individual that has access to the system. A client is an installation of allTags Client, which is accessing the server. By having multiple clients, a person can use multiple allTags installations, like when using different devices. Access permissions as well as changes, made within the system, are attributed to a person, not his or her client(s). It is always possible to add new clients and revoke access to existing ones by deleting them.

Adding people

To allow a new person access to the system, you need to create a personal record with basic details (forename, surname, etc.) as well as at least one client. For any kind of access, permissions must be granted to this person.

There is no fixed limit on how many people (or clients) can be added to the system. Only the amount of concurrently accessing people is limited to 3. To expand this number, you can add expansion keys.

Adding clients

Clients are created from within the details window of a person´s record. When creating a client, you are prompted for a descriptive name so that you can differentiate between them (like 'Workstation office' or 'Travel notebook'). A so-called 'connection string' is generated, which is used on the client to find, verify and register with your allTags Server. Inside the allTags Client, the connection string is entered under settings->server. It can only be used once and within the specified activation period. If the connection string gets lost or the activatation period expires, delete the specific client and create a new one.

• Security information: The connection string includes an one-time usable, time-limited token. It authorizes a generic client to associate itself with one specific person inside an allTags Server. It is therefore important that the connection string is handled by trusted personell or communicated with the end-user over a safe channel. As the registration token works only once, a bad actor can be identified when the proper user is not able connect with the shared connection string. The client can then be disabled by deleting the specific client record on the server.

Removing a client

Removing a client will block access from the corresponding allTags Client installation. Usually, clients are deleted if a connected device has been lost. If all access should be cut off from a person, the person record can be disabled; this will disable all clients as well. Personal records cannot be deleted as they are needed for a full change event history.

Access permissions

Shares are used to grant and restrict access to files in allTags. Files can be assigned to one or multiple shares, allowing different groups of people access to specific content.

It is good practice to create shares following existing structures, like teams, projects or organizational units. As files can be assigned to multiple shares, with different permissions, access can be provided without using transfer directories.

Shares can be added, changed and deleted any time. When a share is deleted, all files, only assigned to this share, are also permanently deleted.

Understanding permissions

Access follows a straightforward permission model. A person or group is granted read, write or set permissions to a particular share. Each higher permission contains all lower ones:

• write includes read
• set includes read and write

To get any access to content inside a share, read access is required. With read access, a person can download, display and make copies of files from inside the system. write access enables changing and deleting files. set permissions allow adding/removing files from and to shares.

If a file exists in multiple shares, the higher access right of a person wins. Example: Some template files are shared via a globally accessible share named Public to all employees of an organization. Everybody has read access to Public. Employees of Human Resources however have set rights and can add to and edit files inside Public to make them globally available.

As seen in the example, permissions work cumulatively. The more shares permissions are assigned, and the more group memberships are granted, the more access a person has.

Group management

A person can be assigned to multiple groups. There is no fixed limit on the number of groups you can create. Permissions assigned to a group are inherit by all people assigned to it.

Groups can currently not be nested (e. g. be assigned to other groups); this keeps permissions easily understandable but is more effort for larger organizations. This might be changed in the future.

Conflict management

When synchronizing content between multiple clients, each of which can be on/offline at different times, there is potential for conflict. Especially, if they work with files that multiple people make regular changes to.

allTags Server recognizes when a client attempts to update a file, which is not based on the latest available version. It then blocks the update and informs the client about the conflict. The user is then asked to resolve the conflict. For this, both versions, the local and the latest server version, are available for comparisson.

To resolve a conflict, the end user must choose whether to overwrite the active server version. Or to void its changes and keep the latest server version undisturbed. In some cases, a user would want to apply some changes to one version or the other. In this case, the user can view (e. g. open a copy in read only mode) the version that is about to be lost, resolve the conflict and then apply the changes to the kept file version.

Logging

There are two kinds of logging for allTags Server.

1. Service logging: Messages, associated with the general application service. You can find these logs in your operating system´s service log. Useful to learn when a service started or why it didn´t.
   • Windows: Windows Logs->Application
   • Linux: syslog
2. Application logging: Messages, generated during regular operation. These logs are stored inside the allTags Server database. They can be viewed and searched via an allTags Client with administrative permissions. Log levels and retention periods can be configured by such a client as well.

Backup and recovery

You need to have regular backups configured for:

• The allTags Server database. If no other tools are prefered, we recommend the backup application Mariabackup, which can be installed as part of MariaDB.
• The working paths for allTags Server, as defined in the server configuration file under paths.
  • You can exclude the temporary directory from the backup. These files do not have any use after a system has been restored.
• The allTags Server certificate files (*.crt and *.key). If lost, all clients must be reconnected to the server.

You might want to also backup the general application configuration file and expansion keys. These are not critical but will help getting allTags Server back online quicker.

Recommended backup strategy

Weekly full and daily incremental backups for files and the database. At least 2 full backups should be kept at any time in case of data loss/corruption. Incremental backups must be kept until the last successful, full backup.

These recommendations are good practice. Depending on the size of your allTags Server instance and your infrastructure, different backup strategies should be employed.

Recovery

To recover, restore files and the database to the latest available version. Make sure that paths, defined in the server configuration file, are correct. If the application service does not start, you can check your operating system´s log for error messages. Depending on your configuration, you might need to re-apply database access permissions for the database user, which is defined in your allTags Server configuration file.

Update

To update allTags Server follow these steps in order:

1. Stop the alltags_server service with your operating system´s service manager.
2. Apply the update
   • Windows: Run the latest installation wizard.
   • Linux: Extract the latest server version to your allTags server application directory. Overwrite existing files.
3. Start the alltags_server service.

Expansion keys

Expansion keys serve to expand the scope and/or the functionality of allTags Server. Currently, they are used to increase the concurrent user limit.

To add expansion keys, place them in the expansionKeys working directory, as defined in the server configuration file under paths. A restart of the application service alltags_server is required for expansion keys to be applied.