Deaddrop Documentation

\pagebreak \tableofcontents \pagebreak

Starting point for this administration guide

At first, you will have to get access to a command line environment at which you can give commands to the system. This is normally available either directly from a console of the system, or remotely accessible via the SSH network protocol.

Console

It is possible to access deaddrop from the console as an administrator.

When using the console is it recommended to use personal accounts and then using sudo to become root. Sudo is configured to use the root password.

SSH

Deaddrop can be set up to use network access via the secure shell, ssh, protocol.

When using SSH is it recommended to use personal accounts and then using sudo to become root. Sudo is configured to use the root password.

Update the system

All updates use RPMs and to update the system use the standard command “yum”. To perform an update, give the command yum upgrade -y and all upgradeable packages will be updated.

Check deaddrop version

To verify which version of deaddrop that is installed, type the following command

rpm -qa deaddrop

the result will display:
[name]-[version]-[build_version].noarch
eg
deaddrop-2.0.4-1501060892.noarch

OS Kernel update

A special case regarding updates is when a new operating system kernel is made available. For kernel updates the system must not only download and install it to run the latest version, a system reboot is needed as well to apply the new changes, including the new kernel. To reboot the system use the command systemctl reboot

Accounts

All local permanent password based accounts will use Session based authentication with an exception for users with the API-role which will use Basic Auth. Basic Auth was default for local password based accounts and was used for all accounts before deaddrop version 3.2. This has change since version 3.2 to session based authentication. Accounts can manually be migrated to the new session based authentication. Administration account is still using Basic Auth.

Adding an ordinary, permanent, deaddrop account

To add a new account for an end-user use the following script with the arguments

/opt/sysctl/deaddrop/admscripts/add_account.pl example@sysctl.se 46123456789 perm

It is very important to note the following, with regards to the input:

  1. the e-mail address must be written in lower case
  2. dont forget to write the country code without an initial “+” sign

Adding an ordinary, permanent x509 or SAML account

x509

After the x509 integration has been set up, accounts will be automatically created for authorized users once the user tries to login to the system.

SAML

After the SAML integration has been set up, account will be automatically created for authorized users once the user tries to login to the system.

Removing an ordinary, permanent, deaddrop account

To remove an account for an end-user use the following script with the argument

/opt/sysctl/deaddrop/admscripts/removedeaddropuser.pl example@sysctl.se

Resetting the password of an ordinary deaddrop account

There is a script to sent out new passwords to people who have forgotten their login password.

The command takes one argument, the username of the user that will get a new password generated and delivered, e.g.

/opt/sysctl/deaddrop/admscripts/reset_password.pl testuser@testdomain.se

Migrate account from Basic Auth to Session based authentication

There is a script to migrate accounts from Basic Auth to session based authentication.

The command takes one argument, the username of the user that will be migrated, e.g.

/opt/sysctl/deaddrop/admscripts/convert_basic_auth_to_session_account.pl testuser@testdomain.se

Adding an administrative account

In the web gui for administrative access, there is functionality to add new administrative user accounts to the system. If you are logged in as a privileged user in the web admin gui, you will have the option “accounts” under the “system” heading in the leftmost column. Clicking on “accounts” will take you to the “ADD AND REMOVE ADMINISTRATIVE ACCOUNTS” section, where you can add new accounts, their passwords and the privilege level that each account should have.

Removing an administrative account

In the web gui for administrative access, there is functionality to remove administrative user accounts from the system. If you are logged in as a privileged user in the web admin gui, you will have the option “accounts” under the “system” heading in the leftmost column. Clicking on “accounts” will take you to the “ADD AND REMOVE ADMINISTRATIVE ACCOUNTS” section, where you can remove accounts. You select which account to remove from the pulldown menu, then click on the button “Remove user account”

Resetting the password of an administrative account

If the administrative user is called “robert”, then the following command will change the password for the admin web gui login for “robert”:

htpasswd -B -C6 /opt/sysctl/ddadm/etc/ddadm/.htpasswd robert

The default user for the administration page is sysadm

Handle existing deaddrops

If a deaddrop is created to the a user like “demo@sysctl.se” a temporary account will be created if the users do not have any permanent account. The account is created in the directory /var/deaddrop/html/demo@sysctl.se/

The uploaded files will be stored in a sub directory like

/var/deaddrop/html/demo@sysctl.se/6ffe03aee5d7ccd78b3b22b6de8d660df141147f129ee806cac5711f7e411d9d

where the last part of the directory is random.

Remove a shared deaddrop

Administration script are available in /opt/sysctl/deaddrop/admscripts/ and the script to remove accounts is removedeaddropuser.pl

To remove a shared deaddrop:

./removedeaddropuser.pl demo@sysctl.se 6ffe03aee5d7ccd78b3b22b6de8d660df141147f129ee806cac5711f7e411d9d

Full example:

[root@localhost ~]# ls /var/deaddrop/html/demo@sysctl.se/
6ffe03aee5d7ccd78b3b22b6de8d660df141147f129ee806cac5711f7e411d9d
[root@localhost ~]# cd /opt/sysctl/deaddrop/admscripts/
[root@localhost admscripts]# ./removedeaddropuser.pl demo@sysctl.se 6ffe03aee5d7ccd78b3b22b6de8d660df141147f129ee806cac5711f7e411d9d

To verify that the account and all files associated with it is removed, check with the following command that will give an error message since the files are not there anymore:

[root@localhost admscripts]# ls /var/deaddrop/html/demo@sysctl.se/
ls: cannot access /var/deaddrop/html/demo@sysctl.se/: No such file or directory

After shared content has been removed and the user was a temporarly account the user directory demo@sysctl.se will also be removed.

Configure deaddrop

Most of the configuration that is used by deaddrop is set in the file /opt/sysctl/deaddrop/conf/admin.conf, and related to that is the default settings for the system, that is stored in the file /opt/sysctl/deaddrop/conf/default/admin.conf.

The file /opt/sysctl/deaddrop/admin.conf is often the only file that needs to be changed after the initial installation. This file can also be configured from the web based graphical administrator interface.

Deaddrop needs to be restarted after a configuration change. Restart deaddrop with the command systemctl restart deaddrop

Multiple domains

Deaddrop supports one or more domain names. If users from a specific domain requires another domain than the default wwwroot in admin.conf can the file /opt/sysctl/deaddrop/conf/internal_users_url.json.example be used as a template by rename the file to /opt/sysctl/deaddrop/conf/internal_users_url.json. The domain is used to check if for a match on a receivers email address and to rewrite the url used in the particular email which will be generated.

[
{"domain":"sysctl.se", "url":"https://deaddrop.sysctl.se"},
{"domain":"sysctl.com", "url":"https://deaddrop.sysctl.com"}
]

This function is normally used for receivers who use SSO for a particular domain.

admin.conf

The text editor vi is installed in the system and can be used to change the settings in /opt/sysctl/deaddrop/conf/admin.conf. To see all the default settings just do

cat /opt/sysctl/deaddrop/conf/default/admin.conf

All configurations in the default config file ends with a comment that explains the setting.

enable global contacts

Enable the global contacts in /opt/sysctl/deaddrop/conf/admin.conf by adding

Global_Contacts_Enable = 1

Edit the file /var/deaddrop/globalcontacts/contacts.json The following example shows how to add 2 global contacts

[{"email":"global_contact@sysctl.se","language":"en","number":"123456789","groups":[],"nick":"global_contact"},{"email":"global_user@sysctl.se","number":"123456780","language":"en","groups":[],"nick":"global_user"}]

The format MUST be valid json

One can use a JSON linter like https://jsonlint.com/ or https://jsononline.net/json-validator for example to validate the json before saving.

user_notification_script

The user_notification_script points by default to the email script which is used to send notifications to users of deaddrop. The notifications could be that a new file has been sent or a reminder to download a file. The script will also notify when files have been removed.

It is possible to change the mail notification to something else by adding a new script that has the same permissions as the default script. The script are required to have to following settings: “-rwxr-x—. root ddadm system_u:object_r:ddbackend_mail_exec_t:s0”

The deaddrop application will call the custom script with json data as argument that must be handled. The argument json will have the following format:

{"from":"sender@sysctl.se","to":"receiver@sysctl.se","lang":"sv","mail_type":"new_file_available"}

The key from indicates the sender of the action and the key to indicates the receiver of the notification. To and From is always an email address.

The key lang will indicate which language the receiver may use. Deaddrop supports the following language as default:

The value for the key mail_type explains what type of notification that should be sent.

The key mail_type can have the following values:

The data that inform the receiver of new files that can be downloaded will also include the sub-path to the website. The key download_dir includes the data to the receivers sub-directory used in the URL.

'{"from":"sender@sysctl.se","to":"receiver@sysctl.se","lang":"en","mail_type":"new_file_available","download_dir":"a9a7aff2a9d58cc1f0ee007f9c2e257a5d15918bfe62625b09b6e783b2ba536e","jobcard":"/var/deaddrop/work/backend/fromcgi/sender@sysctl.seXw9vFynlx3datEBmzPXIq4xS"}'

The data will also include the key jobcard which will point to the directory were job.json exist which has more information that will be used for the job, The json data will include the personal message and the time to live value.

{"sender":{"email":"sender@sysctl.se","number":"4671234567","lang":"en","first_run":"false","accountType":"perm","change_passwd":"false","settings":{"show_number":"true","show_email":"true","show_lang":"false","show_nick":"true"}},"ttl":"8","receivers":[{"email":"receiver@sysctl.se","language":"en","number":"46712345678","name":"","groups":[],"nick":"nickname"}],"ddmessage":"You are allowed to share files delivered by the deaddrop service","create_time":1677585663,"deaddrop_type":"me"}

SMS - gateway.conf

The text-editor vi is installed in the system and can be used to change the settings in /opt/sysctl/sms/conf/gateway.conf. To see all the default settings just do

cat /opt/sysctl/sms/conf/default/gateway.conf.

All configurations in the default config file ends with a comment that explains the setting.

SMS providers

Deaddrop uses SMS to provide passwords to users.

Deaddrop can be used with several different SMS solutions, and several providers. The following options is available as standard

For the modem option to work, a physical modem and a SIM card must be available for the deaddrop service.

For the network SMS services options to work, firewall openings need to be in place to allow Deaddrop to connect to the respective SMS provider endpoint.

Testing the SMS setup

As an verification step, one can use one of the system scripts to see if a SMS can be sent.

/opt/sysctl/deaddrop/scripts/sendsms.pl YOUR-CELLPHONE-NUMBER-HERE test

This way of sending a SMS is sent through the internal SMS queuing system

Troubleshooting an SMS configuration

  1. Sending a simple test text Use the technique listed under “verifying the SMS setup” to try to send an SMS to a cellphone to see that it is working

  2. Test the modem If you have a directly attached SMS modem to the deaddrop, try to use a technique by sending a SMS directly to a modem with the command

/opt/sysctl/sms/admin/testmodem.pl YOUR-CELLPHONE-NUMBER-HERE

IMPORTANT NOTE: THIS COMMAND NORMALLY TAKES JUST ONE ARGUMENT. THE PHONE NUMBER. IT WILL SUPPLY A SHORT TEST TEXT ITSELF.

  1. Another troubleshooting tip is to verify that the SMS queue gets messages queued as well as it gets drained. While logged into the server, check the following directory for files
ls -al /opt/sysctl/sms/work/
  1. restart the SMS backend daemon with the following command

Use the command systemctl to restart the back-end script that run the sms subsystem

systemctl restart ss

Change the time server

Deaddrop uses network time protocol, NTP, to allow for time initiation and time synchronization of the deaddrop host computer.

The file /opt/sysctl/deaddrop/etc/ntp/deaddrop.conf is used to store the time server configuration.

To set a new time server edit the file with vi and change it to the new server, e.g.:

server time.sysctl.se

restart the time service with:

systemctl restart deaddrop-ntpd

For NTP to work correctly, the following prerequisites must be fulfilled:

Change the mail relay

The mail service is configured to use the variable $mydomain and this will usually work out of the box.

The file /opt/sysctl/deaddrop/etc/postfix/main.ddadm.cf is used to store the mail relay server configuration.

To set a new time server edit the file with vi and change it to the new server, e.g.:

relayhost = relay.sysctl.se

restart the mail service with:

systemctl restart deaddrop-postfix

Change the DNS server

Deaddrop depends on DNS and must have a DNS server configured to resolve domain names. To set a DNS server, edit the file /etc/resolv.conf, e.g.:

nameserver 8.8.8.8

Configure deaddrop replica

When deaddrop is configured with higher availability the permanent accounts will be duplicated to a secondary deaddrop server. The secondary server will fetch the latest backup from the master and configure the account. No temporary shares or files will be transferred.

To configure the replica must the primary deaddrop server be configured with a backup account. The username, password and the master domain name must be configured on the slave in /opt/sysctl/ddadm/conf/ddadm.conf, e.q;

backup_username = 'username_for_backup_account'
backup_password = 'password_for_backup_account'
backup_server = 'server.domain.tld'

To activate the account sync must the following services be started:

systemctl enable slave.timer
systemctl start slave.timer
systemctl enable slave_restore.path
systemctl start slave_restore.path

© Copyright sysctl Aktiebolag 2013-2023. All rights reserved