Navigation menu

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Release 8.2

 

Introduction

Welcome to the epiKshare Server Administration Guide. This guide describes administration tasks for epiKshare, the exible open source le synchronization and sharing solution. epiKshare includes the epiKshare server, which runs on Linux, client applications for Microsoft Windows, Mac OS X and Linux, and mobile clients for the Android and Apple iOS operating systems.

Target Audience

This guide is for users who want to install, administer, and optimize their epiKshare servers. To learn more about the epiKshare Web user interface, and desktop and mobile clients, please refer to their respective manuals:

...

epiKshare Android App

epiKshare iOS App

 

 

System Requirements

Memory

Memory requirements for running an epiKshare server are greatly variable, depending on the numbers of users and les, and volume of server activity. epiKshare needs a minimum of 128MB RAM, and we recommend a minimum of 512MB.

 

epiKshare Deployment Recommendations

What is the best way to install and maintain epiKshare? The answer to that is “it depends” because every epiKshare customer has their own particular needs and IT infrastructure. epiKshare and the LAMP stack are highly-congurable, so we will present three typical scenarios and make best-practice recommendations for both software and hardware.

General Recommendations

Note: Whatever the size of your organization, always keep one thing in mind: The amount of data stored in epiKshare will only grow. Plan ahead.

Consider setting up a scale-out deployment, or using Federated Cloud Sharing to keep individual epiKshare instances to a manageable size.

Small Workgroups or Departments

Number of users Up to 150 users.

...

GRAFIK: epiKshare-Server->LDAP-Server/WinAD

Recommended System Requirements

One machine running the application server, Webserver, database server and local storage. Authentication via an existing LDAP or Active Directory server.

...

Storage: Local storage.

 

Mid-sized Enterprises

Number of users: 150 to 1,000 users.

...

High availability level: Every component is fully redundant and can fail without service interruption. Backups without service interruption.

Recommended System Requirements

2 to 4 application servers with 4 sockets and 32GB RAM.

...

Storage: Use an off-the-shelf NFS solution, such as IBM Elastic Storage, RedHat Ceph or SUSE Enterprise Storage.

 

Large Enterprises and Service Providers

Number of users: 5,000 to >100,000 users.

...

High availability level: Every component is fully redundant and can fail without service interruption. Backups without service interruption

Recommended System Requirements

4 to 20 application/Webservers.

...

Authentication via an existing LDAP or Active Directory server, or SAML.

GRAFIK: Admin S 17

Hardware Considerations

Solid-state drives (SSDs) for I/O.

...

The amount of data in epiKshare tends to continually grow. Eventually a single machine will not scale; I/O performance decreases and becomes a bottleneck with multiple up- and downloads, even with solid-state drives.


Scale-Out Deployment

Scale-Out Deployment

Provider setup:

...

Currently DB le cache table will grow rapidly, making migrations painful in case the table is altered.

 

What about Nginx / PHP-FPM?

Could be used instead of Haproxy as the load balancer. But on uploads stores the whole le on disk before handing it over to PHP-FPM.

 

A Single Master DB is Single Point of Failure, Does Not Scale

When master fails another slave can become master. However, the increased complexity carries some risks: Multi master has the risk of splitbrain, and deadlocks. EpiKshare tries to solve the problem of deadlocks with high-level le locking.

 

 

File Storage

While many customers are starting with NFS, sooner or later that requires scale-out storage. Currently the options are GPFS or GlusterFS, or an object store protocol like S3 (supported in Enterprise Edition only) or Swift. S3 also allows access to Ceph Storage.

 

Session Storage

Redis: provides persistence, nice graphical inspection tools available, supports epiKshare high-level lelocking.

If Shibboleth is a requirement you must use Memcached, and it can also be used to scale-out shibd session storage (see Memcache StorageService).

 

Installation notices

Downgrading not supported

Downgrading is not supported and risks corrupting your data! If you need to revert to an older epiKshare version, install it from scratch and then restore your data from backup. Before doing this, le a support ticket and ask for help to see if your issue can be resolved without downgrading.

 

Additional Installation Guides and Notes

For guidance on how to install the epiKshare appliance, please refer to our guide "Deploying an epiKshare server on-premise".

 

Trusted Domains

All URLs used to access your epiKshare server must be whitelisted in your config le, under the trusted_domains setting. Users are allowed to log into epiKshare only when they point their browsers to a URL that is listed in the trusted_domains setting. You may use IP addresses and domain names. A typical conguration looks like this:

...

The loopback address, 127.0.0.1, is automatically whitelisted, so as long as you have access to the physical server you can always login. In the event that a load balancer is in place there will be no issues as long as it sends the correct X-Forwarded-Host header. When a user tries a URL that is not whitelisted, an error appears – telling that the user is accessing epiKshare from an untrusted domain. If clicking the button on the warning message site doesn't work, please contact the epiKshare support to manually edit the configuration file for you.

 

Setting Strong Directory Permissions

For hardened security we recommend setting the permissions on your epiKshare directories as strictly as possible, and for proper server operations. This should be done immediately after the initial installation and before running the setup. Your HTTP user must own the config/, data/ and apps/ directories so that you can congure epiKshare, create, modify and delete your data les, and install apps via the epiKshare Web interface. You can nd your HTTP user in your HTTP server conguration les. Or you can use PHP Version and Information (Look for the User/Group line).

...

These strong permissions prevent upgrading your epiKshare server. To change the permissions for an upgrade, please contact an epiKshare tech representative.

 

Working with Apps and Adding Apps

Workin with unapproved apps and installing apps to your epiKshare appliance is currently not supported.

If you need extended functionality for your epiKshare installation, please contact the epiKshare support.

 

Enabling SSL

***Doku von Bene***

 

PHP-FPM

If you plan to use PHP-FPM, please contact the epiKshare support.

 

epiKshare Server Configuration

Warnings on Admin Page

Your epiKshare server has a built-in conguration checker, and it reports its ndings at the top of your Admin page. These are some of the warnings you might see, and what to do about them.

Security & setup warnings

No memory cache has been congured. To enhance your performance please congure a memcache if available.”

You can signicantly improve your epiKshare server performance with memory caching, where frequently-requested objects are stored in memory for faster retrieval. There are two types of caches to use: a PHP opcode cache, which is commonly called opcache, and data caching for your Web server. If you do not install and enable a local memcache you will see a warning on your epiKshare admin page. A memcache is not required and you may safely ignore the warning if you prefer. If you need to enable caching, please get in touch with the epiKshare support.

 

You are accessing this site via HTTP. We strongly suggest you congure your server to require using HTTPS instead.”

Please take this warning seriously; using HTTPS is a fundamental security measure. You must congure your Web server to support it, and then there are some settings in the Security section of your epiKshare Admin page to enable.

For guidance on how to enable SSL, please refer to "Enabling SSL".

 

Configuring the Activity App

You can congure your epiKshare server to automatically send out e-mail notications to your users for various events like:

...

To congure your epiKshare to send out e-mail notications a working Email Conguration is mandatory. Please set up the email configuration on the Admin page.

 

Enabling ClamAV

If you need to enable virus scanning on your epiKshare installation, please contact an epiKshare tech representative from the epiKshare support.

 

Advanced configuration of background activities

If you need to change the configuration of background activities to CRON, please contact an epiKshare tech representative from the epiKshare support.


Email Configuration

epiKshare is capable of sending password reset emails, notifying users of new leshares, changes in les, and activity notications. Your users congure which notications they want to receive on their Personal pages. epiKshare does not contain a full email server, but rather connects to your existing mail server. You must have a functioning mail server for epiKshare to be able to send emails. You may have a mail server on the same machine as epiKshare, or it may be a remote server.

...

Note: The Sendmail option refers to the Sendmail SMTP server, and any drop-in Sendmail replacement such as Postx, Exim, or Courier. All of these include a sendmail binary, and are freely-interchangeable.

Configuring an SMTP Server

You need the following information from your mailserver administrator to connect epiKshare to a remote SMTP server:

...

If you received this email, the settings seem to be correct.

Configuring PHP and Sendmail

Conguring PHP or Sendmail requires only that you select one of them, and then enter your desired return address.

...

In most cases the smtp option is best, because it removes the extra step of passing through PHP, and you can control all of your mail server options in one place, in your mail server conguration.

Using Email Templates

Another useful new feature is editable email templates. Now you can edit epiKshare’s email templates on your Admin page. These are your available templates: • Sharing email (HTML) – HTML version of emails notifying users of new le shares

...

Note: You can edit the templates directly in the template text box, or you can copy and paste them to a text editor for modication and then copy and paste them back to the template text box for use when you are done.

 

Linking External Sites

This is useful for quick access to important Web pages such as the epiKshare manuals and informational pages for your company, and for presenting external pages.

...

There isn’t much you can do about these issues, but if you’re curious you can see what is happening.

 

Language Configuration

In normal cases epiKshare will automatically detect the language of the Web-GUI. If this does not work properly or you want to make sure that epiKshare always starts with a given language, please contact the epiKshare support to have your configuration changed accordingly.

 

Logging Configuration

Use your epiKshare log to review system status, or to help debug problems. Logging levels range from DEBUG, which logs all activity, to FATAL, which logs only fatal errors.

...

By default the log level is set to 2 (WARN). Use DEBUG when you have a problem to diagnose, and then reset your log level to a less-verbose level as DEBUG outputs a lot of information, and can affect your server performance.

 

Hardening and Security Guidance

epiKshare aims to ship with secure defaults that do not need to get modied by administrators. However, in some cases some additional security hardening can be applied in scenarios where the administrator has complete control over the epiKshare instance.

Note: epiKshare will warn you in the administration interface if some critical security-relevant options are missing. However, it is still up to the server administrator to review and maintain system security.

Please inform an epiKshare tech representative if you need advice to secure and/or harden your system.

 

Deployment

For guidance on how to deploy epiKshare, please refer to this article in our knowledge base.

 

Ensure that your epiKshare instance is installed in a DMZ

As epiKshare supports features such as Federated File Sharing we do not consider Server Side Request Forgery (SSRF) part of our threat model. In fact, given all our external storage adapters this can be considered a feature and not a vulnerability. This means that a user on your epiKshare instance could probe whether other hosts are accessible from the epiKshare network. If you do not want this you need to ensure that your epiKshare is properly installed in a segregated network and proper rewall rules are in place.

 

Reverse Proxy Configuration

epiKshare can be run through a reverse proxy, which can cache static assets such as images, CSS or JS les, move the load of handling HTTPS to a different server or load balance between multiple servers. If you want to run epiKshare with behind a reverse proxy, please contact an epiKshare tech representative.

 

Server Tuning & Performance Tips

Use cron to perform background jobs

If you want to use CRON to perform background tasks, please contact an epiKshare tech representative.

 

Caching

If you need to enable memory caching for your epiKshare installation, please contact an epiKshare tech representative.

 

JavaScript and CSS Asset Management

In production environments, JavaScript and CSS les should be delivered in a concatenated and compressed format. If you need to change settings regarding the delivery of JavaScript and CSS files, please contact the epiKshare support.

 

User Management

On the User management page of your epiKshare Web UI you can:

...

User accounts have the following properties: Login Name (Username) The unique ID of an epiKshare user, and it cannot be changed. Full Name The user’s display name that appears on leshares, the epiKshare Webinterface, and emails. Admins and users may change the Full Name anytime. If the Full Name is not set it defaults to the login name. Password The admin sets the new user’s rst password. Both the user and the admin can change the user’s password at anytime. Groups You may create groups, and assign group memberships to users. By default new users are not assigned to any groups. Group Admin Group admins are granted administrative privileges on specic groups, and can add and remove users from their groups. Quota The maximum disk space assigned to each user. Any user that exceeds the quota cannot upload or sync data. You have the the option to include external storage in user quotas.

 

Creating a New User

To create a user account:

...

Login names may contain letters (a-z, A-Z), numbers (0-9), dashes (-), underscores (_), periods (.) and at signs (@). After creating the user, you may ll in their Full Name if it is different than the login name, or leave it for the user to complete. If you have checked Send email to new user in the control panel on the lower left sidebar, you may also enter the new user’s email address, and epiKshare will automatically send them a notication with their new login information. You may edit this email using the email template editor on your Admin page.

 

Reset a User's Password

You cannot recover a user's password, but you can set a new one:

...

If you have encryption enabled, there are special considerations for user password resets. Please make sure you have created a recovery password for the user files before you reset a user's password.

 

Renaming a User

Each epiKshare user has two names: a unique Login Name used for authentication, and a Full Name, which is their display name. You can edit the display name of a user, but you cannot change the login name of any user. To set or change a user’s display name:

...

Enter the user’s new display name

 

Granting Administrator Privileges to a User

epiKshare has two types of administrators: Super Administrators and Group Administrators. Group administrators have the rights to create, edit and delete users in their assigned groups. Group administrators cannot access system settings, or add or modify users in the groups that they are not Group Administrators for. Use the dropdown menus in the Group Admin column to assign group admin privileges.

Super Administrators have full rights on your epiKshare server, and can access and modify all settings. To assign the Super Administrators role to a user, simply add them to the admin group.

Managing Groups

You can assign new users to groups when you create them, and create new groups when you create new users. You may also use the Add Group button at the top of the left pane to create new groups. New group members will immediately have access to file shares that belong to their new groups.

Setting Storage Quotas

Click the gear on the lower left pane to set a default storage quota. This is automatically applied to new users. You may assign a different quota to any user by selecting from the Quota dropdown, selecting either a preset value or entering a custom value. When you create custom quotas, use the normal abbreviations for your storage values such as 500 MB, 5 GB, 5 TB, and so on.

...

When a user creates a public share via URL, and allows uploads, any uploaded files count against that user’s quota.

Deleting users

Deleting a user is easy: hover your cursor over their name on the Users page until a trashcan icon appears at the far right. Click the trashcan, and they’re gone. You’ll see an undo button at the top of the page, which remains until you refresh the page. When the undo button is gone you cannot recover the deleted user.

All of the files owned by the user are deleted as well, including all files they have shared. If you need to preserve the user’s files and shares, you must first download them from your epiKshare Files page, which compresses them into a zip file, or use a sync client to copy them to your local computer. See File Sharing to learn how to create persistent file shares that survive user deletions.

Resetting a Lost Admin Password

The normal ways to recover a lost password are:

...

If neither of these is an option, then you have a third option, and that is contacting the epiKshare support.

User Authentication with IMAP, SMB, and FTP

Info
Note: A non-blocking or correctly configured SELinux setup is needed for these backends to work.

If you need to use one of the following authentication methods, please ask an epiKshare technician for assistance: IMAP, SMB, FTP.

User Authentication with LDAP

epiKshare ships with an LDAP application to allow LDAP users (including Active Directory) to appear in your epiKshare user listings. These users will authenticate to epiKshare with their LDAP credentials, so you don’t have to create separate epiKshare user accounts for them. You will manage their epiKshare group memberships, quotas, and sharing permissions just like any other epiKshare user.

...

Info
Note: A non-blocking or correctly configured SELinux setup is needed for the LDAP backend to work.

 

Configuration

 

Info
titleWarning

We strongly encourage you to get help with the configuration from the epiKshare team. Please only proceed if you know exactly what you're doing.

 

...

The LDAP configuration panel has four tabs. A correctly completed first tab (“Server”) is mandatory to access the other tabs. A green indicator lights when the configuration is correct. Hover your cursor over the fields to see some pop-up tooltips.

Server Tab

Start with the Server tab. You may configure multiple servers if you have them. At a minimum you must supply the LDAP server’s hostname. If your server requires authentication, enter your credentials on this tab. epiKshare will then attempt to auto-detect the server’s port and base DN. The base DN and port are mandatory, so if epiKshare cannot detect them you must enter them manually.

...

Host: The host name or IP address of the LDAP server. It can also be a ldaps:// URI. If you enter the port number, it speeds up server detection.

Examples:

Port: The port on which to connect to the LDAP server. The field is disabled in the beginning of a new configuration. If the LDAP server is running on a standard port, the port will be detected automatically. If you are using a non-standard port, epiKshare will attempt to detect it. If this fails you must enter the port number manually.

Example:
  • 389

User DN: The name as DN of a user who has permissions to do searches in the LDAP directory. Leave it empty for anonymous access. We recommend that you have a special LDAP system user for this.

Example:
  • uid=epiKsharesystemuser,cn=sysusers,dc=my-company,dc=com

...

Base DN: The base DN of LDAP, from where all users and groups can be reached. You may enter multiple base DNs, one per line. (Base DNs for users and groups can be set in the Advanced tab.) This field is mandatory. epiKshare attempts to determine the Base DN according to the provided User DN or the provided Host, and you must enter it manually if epiKshare does not detect it.

Example:
  • dc=my-company,dc=com

User Filter

Use this to control which LDAP users are listed as epiKshare users on your epiKshare server. In order to control which LDAP users can login to your epiKshare server use the Login filter. Those LDAP users who have access but are not listed as users (if there are any) will be hidden users. You may bypass the form fields and enter a raw LDAP filter if you prefer.

...

Edit raw filter instead: Clicking on this text toggles the filter mode and you can enter the raw LDAP filter directly.

Example:
(&(objectClass=inetOrgPerson)(memberOf=cn=epiKshareusers,ou=groups, dc=example,dc=com))

x users found: This is an indicator that tells you approximately how many users will be listed in epiKshare. The number updates automatically after any changes.

Login Filter

The settings in the Login Filter tab determine which LDAP users can log in to your epiKshare system and which attribute or attributes the provided login name is matched against (e.g. LDAP/AD username, email address). You may select multiple user details. (You may bypass the form fields and enter a raw LDAP filter if you prefer.)

...

The %uid placeholder is replaced with the login name entered by the user upon login.

Examples:
  • only username:

(&(objectClass=inetOrgPerson)(memberOf=cn=epiKshareusers,ou=groups, dc=example,dc=com)(uid=%uid)

...

((&(objectClass=inetOrgPerson)(memberOf=cn=epiKshareusers,ou=groups, dc=example,dc=com)(|(uid=%uid)(mail=%uid)))

Group Filter

By default, no LDAP groups will be available in epiKshare. The settings in the group filter tab determine which groups will be available in epiKshare. You may also elect to enter a raw LDAP filter instead.

...

Edit raw filter instead: Clicking on this text toggles the filter mode and you can enter the raw LDAP filter directly.

Example:
  • objectClass=group
  • objectClass=posixGroup

...

y groups found: This tells you approximately how many groups will be available in epiKshare. The number updates automatically after any change.

Advanced Settings

The LDAP Advanced Setting section contains options that are not needed for a working connection. This provides controls to disable the current configuration, configure replica hosts, and various performance-enhancing options.

...

  • Connection Settings

  • Directory Settings

  • Special Attributes

Connection Settings

Configuration Active: Enables or Disables the current configuration. By default, it is turned off. When epiKshare makes a successful test connection it is automatically turned on.

Backup (Replica) Host: If you have a backup LDAP server, enter the connection settings here. epiKshare will then automatically connect to the backup when the main server cannot be reached. The backup server must be a replica of the main server so that the object UUIDs match.

Example:

...

Note that almost every PHP request requires a new connection to the LDAP server. If you require fresh PHP requests we recommend defining a minimum lifetime of 15s or so, rather than completely eliminating the cache.

Examples:
  • ten minutes: 600

  • one hour: 3600

See the Caching section below for detailed information on how the cache operates.

Directory Settings

User Display Name Field: The attribute that should be used as display name in epiKshare.

  • Example:
    displayName

2nd User Display Name Field: An optional second attribute displayed in brackets after the display name, for example using the mail attribute displays as Molly Foo (molly@example.com).

Base User Tree: The base DN of LDAP, from where all users can be reached. This must be a complete DN, regardless of what you have entered for your Base DN in the Basic setting. You can specify multiple base trees, one on each line.

  • Example:
cn=programmers,dc=my-company,dc=com cn=designers,dc=my-company,dc=com

...

If an attribute is not available on a user object, the user will not be listed, and will be unable to login. This also affects the display name attribute. If you override the default you must specify the display name attribute here.

  • Example:
displayName mail

Group Display Name Field: The attribute that should be used as epiKshare group name. epiKshare allows a limited set of characters (a-zA-Z0-9.-_@). Once a group name is assigned it cannot be changed.

  • Example: 
    cn

Base Group Tree: The base DN of LDAP, from where all groups can be reached. This must be a complete DN, regardless of what you have entered for your Base DN in the Basic setting. You can specify multiple base trees, one in each line.

  • Example:
cn=barcelona,dc=my-company,dc=com cn=madrid,dc=my-company,dc=com

...

If you override the default, the group display name attribute will not be taken into account, unless you specify it as well.

  • Example:
cn description

Group Member association: The attribute that is used to indicate group memberships, i.e. the attribute used by LDAP groups to refer to their users.

epiKshare detects the value automatically. You should only change it if you have a very valid reason and know what you are doing.

  • Example: 
    uniquemember

Special Attributes

Quota Field: epiKshare can read an LDAP attribute and set the user quota according to its value. Specify the attribute here, and it will return human-readable values, e.g. “2 GB”. Any quota set in LDAP overrides quotas set on the epiKshare user management page.

  • Example: 
    epiKshareQuota

Quota Default: Override epiKshare default quota for LDAP users who do not have a quota set in the Quota Field.

  • Example: 
    15 GB

Email Field: Set the user’s email from their LDAP attribute. Leave it empty for default behavior.

  • Example: 
    mail

User Home Folder Naming Rule: By default, the epiKshare server creates the user directory in your epiKshare data directory and gives it the epiKshare username, .e.g /var/www/epiKshare/data/alice. You may want to override this setting and name it after an LDAP attribute value. The attribute can also return an absolute path, e.g. /mnt/storage43/alice. Leave it empty for default behavior.

  • Example:
    cn

In all epiKshare installations the home folder rule is enforced. This means that once you set a home folder naming rule (get a home folder from an LDAP attribute), it must be available for all users. If it isn’t available for a user, then that user will not be able to login. Also, the filesystem will not be set up for that user, so their file shares will not be available to other users.

Expert Settings

In the Expert Settings fundamental behavior can be adjusted to your needs. The configuration should be well-tested before starting production use.

...

You can override all of this with the Internal Username setting. Leave it empty for default behaviour. Changes will affect only newly mapped LDAP users.

  • Example: 
    uid

Override UUID detection: By default, epiKshare auto-detects the UUID attribute. The UUID attribute is used to uniquely identify LDAP users and groups. The internal username will be created based on the UUID, if not specified otherwise.

You can override the setting and pass an attribute of your choice. You must make sure that the attribute of your choice can be fetched for both users and groups and it is unique. Leave it empty for default behaviour. Changes will have effect only on newly mapped LDAP users and groups. It also will have effect when a user’s or group’s DN changes and an old UUID was cached, which will result in a new user. Because of this, the setting should be applied before putting epiKshare in production use and clearing the bindings (see the User and Group Mapping section below).

  • Example: 
    cn

Username-LDAP User Mapping: epiKshare uses usernames as keys to store and assign data. In order to precisely identify and recognize users, each LDAP user will have a internal username in epiKshare. This requires a mapping from epiKshare username to LDAP user. The created username is mapped to the UUID of the LDAP user. Additionally the DN is cached as well to reduce LDAP interaction, but it is not used for identification. If the DN changes, the change will be detected by epiKshare by checking the UUID value.

...

Clearing the Mappings is not configuration sensitive, it affects all LDAP configurations!

Testing the configuration

The Test Configuration button checks the values as currently given in the input fields. You do not need to save before testing. By clicking on the button, epiKshare will try to bind to the epiKshare server using the settings currently given in the input fields. If the binding fails you’ll see a yellow banner with the error message “The configuration is invalid. Please have a look at the logs for further details.”

When the configuration test reports success, save your settings and check if the users and groups are fetched correctly on the Users page.

epiKshare Avatar integration

epiKshare supports user profile pictures, which are also called avatars. If a user has a photo stored in the jpegPhoto or thumbnailPhoto attribute on your LDAP server, it will be used as their avatar. In this case the user cannot alter their avatar (on their Personal page) as it must be changed in LDAP. jpegPhoto is preferred over thumbnailPhoto.

...

Photos served from LDAP are automatically cropped and resized in epiKshare. This affects only the presentation, and the original image is not changed.

Troubleshooting, Tips and Tricks

SSL Certificate Verification (LDAPS, TLS)

A common mistake with SSL certificates is that they may not be known to PHP. If you have trouble with certificate validation make sure that

  • You have the certificate of the server installed on the epiKshare server

  • The certificate is announced in the system’s LDAP configuration file (usually /etc/ldap/ldap.conf

  • Using LDAPS, also make sure that the port is correctly configured (by default 636)

Microsoft Active Directory

Compared to earlier epiKshare versions, no further tweaks need to be done to make epiKshare work with Active Directory. epiKshare will automatically find the correct configuration in the set-up process.

memberOf / Read MemberOf permissions

If you want to use memberOf within your filter you might need to give your querying user the permissions to use it. For Microsoft Active Directory this is described here.

Duplicating Server Configurations

In case you have a working configuration and want to create a similar one or “snapshot” configurations before modifying them you can do the following:

...

Now you can modify and enable the configuration.

epiKshare LDAP Internals

User and Group Mapping

In epiKshare the user or group name is used to have all relevant information in the database assigned. To work reliably a permanent internal user name and group name is created and mapped to the LDAP DN and UUID. If the DN changes in LDAP it will be detected, and there will be no conflicts.

...

That means that your LDAP configuration should be good and ready before putting it into production. The mapping tables are filled early, but as long as you are testing, you can empty the tables any time. Do not do this in production.

Caching

The LDAP cache is only a memory cache, and you must install and configure the memory cache. The epiKshare Cache helps to speed up user interactions and sharing. It is populated on demand, and remains populated until the Cache Time-To-Live for each unique request expires. User logins are not cached, so if you need to improve login times set up a slave LDAP server to share the load.

In order to enable caching, please get in touch with the epiKshare support.

Handling with Backup Server

When epiKshare is not able to contact the main LDAP server, epiKshare assumes it is offline and will not try to connect again for the time specified in Cache Time-To-Live. If you have a backup server configured epiKshare will connect to it instead. When you have scheduled downtime, check Disable Main Server to avoid unnecessary connection attempts.

LDAP User Cleanup

LDAP User Cleanup is a new feature in the LDAP user and group backend application. LDAP User Cleanup is a background process that automatically searches the epiKshare LDAP mappings table, and verifies if the LDAP users are still available. Any users that are not available are marked as deleted in the database. Please consider to get technical assistance by the epiKshare support in order to automate this task.

User Provisioning API

The Provisioning API application enables a set of APIs that external systems can use to create, edit, delete and query user attributes, query, set and remove groups, set quota and query total storage used in epiKshare. Group admin users can also query epiKshare and perform the same functions as an admin for groups they manage. The API also enables an admin to query for active epiKshare applications, application info, and to enable or disable an app remotely. HTTP requests can be used via a Basic Auth header to perform any of the functions listed above. The Provisioning API app is enabled by default.

The base URL for all calls to the share API is epiKshare_base_url/ocs/v1.php/cloud.

Instruction Set For Users

users / adduser

Create a new user on the epiKshare server. Authentication is done by sending a basic HTTP authentication header. Syntax: ocs/v1.php/cloud/users

...

  • 100 - successful

  • 101 - invalid input data

  • 102 - username already exists

  • 103 - unknown error occurred whilst adding the user

Example
XML Output
<?xml version="1.0"?>
<ocs>
<meta>
<status>ok</status>
<statuscode>100</statuscode>
<message/>
</meta>
<data/>
</ocs>

users / getusers

Retrieves a list of users from the epiKshare server. Authentication is done by sending a Basic HTTP Authorization header.

...

Status codes:

  • 100 - successful

Example
XML Output
<?xml version="1.0"?>
<ocs>
<meta>
<statuscode>100</statuscode>
<status>ok</status>
</meta>
<data>
<users>
<element>Frank</element>
</users>
</data> </ocs>

users / getuser

Retrieves information about a single user. Authentication is done by sending a Basic HTTP Authorization header. Syntax: ocs/v1.php/cloud/users/{userid}

...

Status codes:

  • 100 - successful

Example
XML Output
<?xml version="1.0"?>
<ocs>
<meta>
<statuscode>100</statuscode>
<status>ok</status>
</meta>
<data> <email>frank@example.org</email>
<quota>0</quota>
<enabled>true</enabled>
</data> </ocs>

users / edituser

Edits attributes related to a user. Users are able to edit email, displayname and password; admins can also edit the quota value. Authentication is done by sending a Basic HTTP Authorization header.

...

  • 100 - successful

  • 101 - user not found

  • 102 - invalid input data

Examples
XML Output
<?xml version="1.0"?>
<ocs>
<meta>
<statuscode>100</statuscode>
<status>ok</status>
</meta>
<data/>
</ocs>

users / deleteuser

Deletes a user from the epiKshare server. Authentication is done by sending a Basic HTTP Authorization header. Syntax: ocs/v1.php/cloud/users/{userid}

...

  • 100 - successful

  • 101 - failure

Example

 

Deletes the user Frank 


XML Output

 

<?xml version="1.0"?>
<ocs>
<meta>
<statuscode>100</statuscode>
<status>ok</status>
</meta>
<data/> </ocs>

users / getgroups

Retrieves a list of groups the specified user is a member of. Authentication is done by sending a Basic HTTP Authorization header.

...

Status codes:

  • 100 - successful

Example
XML Output
<?xml version="1.0"?>
<ocs>
<meta>
<statuscode>100</statuscode>
<status>ok</status>
</meta>
<data>
<groups>
<element>admin</element>
<element>group1</element>
</groups>
</data> </ocs>

users / addtogroup

Adds the specified user to the specified group. Authentication is done by sending a Basic HTTP Authorization header. Syntax: ocs/v1.php/cloud/users/{userid}/groups

...

  • 100 - successful

  • 101 - no group specified

  • 102 - group does not exist

  • 103 - user does not exist

  • 104 - insufficient privileges

  • 105 - failed to add user to group

Example
XML Output
<?xml version="1.0"?>
<ocs>
<meta>
<statuscode>100</statuscode>
<status>ok</status>
</meta>
<data/>
</ocs>

users / removefromgroup

Removes the specified user from the specified group. Authentication is done by sending a Basic HTTP Authorization header.

...

  • 100 - successful

  • 101 - no group specified

  • 102 - group does not exist

  • 103 - user does not exist

  • 104 - insufficient privileges

  • 105 - failed to remove user from group

Example
XML Output
<?xml version="1.0"?>
<ocs>
<meta>
<statuscode>100</statuscode>
<status>ok</status>
</meta>
<data/> </ocs>

users / createsubadmin

Makes a user the subadmin of a group. Authentication is done by sending a Basic HTTP Authorization header. Syntax: ocs/v1.php/cloud/users/{userid}/subadmins

...

  1. - group does not exist

  2. - unknown failure

Example
XML Output
<?xml version="1.0"?>
<ocs>
<meta>
<statuscode>100</statuscode>
<status>ok</status>
</meta>
<data/> </ocs>

users / removesubadmin

Removes the subadmin rights for the user specified from the group specified. Authentication is done by sending a Basic HTTP Authorization header.

...

  • 100 - successful

  • 101 - user does not exist

  • 102 - user is not a subadmin of the group / group does not exist

  • 103 - unknown failure

Example
XML Output
<?xml version="1.0"?>
<ocs>
<meta>
<statuscode>100</statuscode>
<status>ok</status>
</meta>
<data/> </ocs>

users / getsubadmingroups

Returns the groups in which the user is a subadmin. Authentication is done by sending a Basic HTTP Authorization header.

...

  • 100 - successful

  • 101 - user does not exist

  • 102 - unknown failure

Example
XML Output
<?xml version="1.0"?>
<ocs>
<meta>
<status>ok</status>
<statuscode>100</statuscode>
<message/>
</meta>
<data>
<element>testgroup</element>
</data>
</ocs>

Instruction Set For Groups

groups / getgroups

Retrieves a list of groups from the epiKshare server. Authentication is done by sending a Basic HTTP Authorization header.

...

Status codes:

  • 100 - successful

Example
XML Output
<?xml version="1.0"?>
<ocs>
<meta>
<statuscode>100</statuscode>
<status>ok</status>
</meta>
<data>
<groups>
<element>admin</element>
</groups>
</data> </ocs>

groups / addgroup

Adds a new group. Authentication is done by sending a Basic HTTP Authorization header.

...

  • 100 - successful

  • 101 - invalid input data

  • 102 - group already exists

  • 103 - failed to add the group

Example
XML Output
<?xml version="1.0"?>
<ocs>
<meta>
<statuscode>100</statuscode>
<status>ok</status>
</meta>
<data/> </ocs>

groups / getgroup

Retrieves a list of group members. Authentication is done by sending a Basic HTTP Authorization header.

...

Status codes:

  • 100 - successful

Example
XML Output
<?xml version="1.0"?>
<ocs>
<meta>
<statuscode>100</statuscode>
<status>ok</status>
</meta>
<data>
<users>
<element>Frank</element>
</users>
</data> </ocs>

groups / getsubadmins

Returns subadmins of the group. Authentication is done by sending a Basic HTTP Authorization header.

...

  1. - successful

  2. - group does not exist

• 102 - unknown failure

Example
XML Output
<?xml version="1.0"?>
<ocs>
<meta>
<status>ok</status>
<statuscode>100</statuscode>
<message/>
</meta>
<data>
<element>Tom</element>
</data> </ocs>

groups / deletegroup

Removes a group. Authentication is done by sending a Basic HTTP Authorization header.

...

  • 100 - successful

  • 101 - group does not exist

  • 102 - failed to delete group

Example
XML Output
<?xml version="1.0"?>
<ocs>
<data>
<meta>
<statuscode>100</statuscode>
<status>ok</status>
</meta>
<data/>
</ocs>

Instruction Set For Apps

apps / getapps

Returns a list of apps installed on the epiKshare server. Authentication is done by sending a Basic HTTP Authorization header.

...

  • 100 - successful

  • 101 - invalid input data

Example
XML Output
<?xml version="1.0"?>
<ocs>
<meta>
<statuscode>100</statuscode>
<status>ok</status>
</meta>
<data>
<apps>
<element>files</element>
<element>provisioning_api</element>
</apps>
</data> </ocs>

apps / getappinfo

Provides information on a specific application. Authentication is done by sending a Basic HTTP Authorization header. Syntax: ocs/v1.php/cloud/apps/{appid}

...

Status codes:

  • 100 - successful

Example
XML Output
<?xml version="1.0"?>
<ocs>
<meta>
<statuscode>100</statuscode>
<status>ok</status>
</meta>
<data>
<info/>
<remote>
<files>appinfo/remote.php</files>
<webdav>appinfo/remote.php</webdav>
<filesync>appinfo/filesync.php</filesync>
</remote>
<public/>
<id>files</id>
<name>Files</name>
<description>File Management</description>
<licence>AGPL</licence>
<author>Robin Appelman</author>
<require>4.9</require>
<shipped>true</shipped>
<standalone></standalone>
<default_enable></default_enable>
<types>
<element>filesystem</element>
</types>
</data> </ocs>

apps / enable

Enable an app. Authentication is done by sending a Basic HTTP Authorization header.

...

Status codes:

  • 100 - successful

Example
XML Output
<?xml version="1.0"?>
<ocs>
<meta>
<statuscode>100</statuscode>
<status>ok</status>
</meta> </ocs>

apps / disable

Disables the specified app. Authentication is done by sending a Basic HTTP Authorization header.

...

Status codes:

  • 100 - successful

Example
XML Output
<?xml version="1.0"?>
<ocs>
<meta>
<statuscode>100</statuscode>
<status>ok</status>
</meta>
</ocs>

File Sharing and Management

epiKshare users can share files with their epiKshare groups and other users on the same epiKshare server, with epiKshare users on other epiKshare servers, and create public shares for people who are not epiKshare users. You have control of a number of user permissions on file shares:

...

Info
epiKshare does not preserve the mtime (modification time) of directories, though it does update the mtimes on files.

File Sharing

Creating Persistent File Shares

When a user is deleted, their files are also deleted. As you can imagine, this is a problem if they created file shares that need to be preserved, because these disappear as well. In epiKshare files are tied to their owners, so whatever happens to the file owner also happens to the files.

One solution is to create persistent shares for your users. You can retain ownership of them, or you could create a special user for the purpose of establishing permanent file shares. Simply create a shared folder in the usual way, and share it with the users or groups who need to use it. Set the appropriate permissions on it, and then no matter which users come and go, the file shares will remain. Because all files added to the share, or edited in it, automatically become owned by the owner of the share regardless of who adds or edits them.

Configuring Federated Cloud Sharing

With just a few clicks you can easily and securely link file shares between epiKshare servers, in effect creating a cloud of epiKshares. You can automatically send an email notification when you create the share, share directly with users on other epiKshare servers, add password protection, allow users to upload files, and set an expiration date.

...

Info

Currently, Federated shares cannot be re-shared, and the only permissions option when you create the share is “Can edit”.

 

Follow these steps to create a new Federated Cloud share:

...

Click the trash can icon to disconnect the share.


Creating Federated Cloud Shares via Public Link Share

Check the Share Link checkbox to expose more sharing options (which are described more fully in File Sharing). You may create a federated cloud share by allowing epiKshare to create a public link for you, and then email it to the person you want to create the share with.

...

Un-check the Share Link checkbox to disable any federated cloud share created this way.

Configuration Tips

The Sharing section on your Admin page allows you to control how your users manage federated cloud shares:

...

Your epiKshare server creates the share link from the URL that you used to log into the server, so make sure that you log into your server using a URL that is accessible to your users. For example, if you log in via its LAN IP address, such as http://192.168.10.50, then your share URL will be something like http://192.168.10.50/epiKshare/index.php/s/jWfCfTVztGlWTJe, which is not accessible outside of your LAN. This also applies to using the server name; for access outside of your LAN you need to use a fully qualified domain name such as http://myserver.example.com, rather than http://myserver.

Uploading big files > 512MB

The default maximum file size for uploads is 512MB. You can increase this limit up to what your filesystem and operating system allows. There are certain hard limits that cannot be exceeded:

...

Info
The epiKshare sync client is not affected by these upload limits as it is uploading files in smaller chunks.

System Configuration

  • Disable user quotas, which makes them unlimited

  • Your temp file or partition has to be big enough to hold multiple parallel uploads from multiple users; e.g. if the max upload size is 10GB and the average number of users uploading at the same time is 100: temp space has to hold at least 10x100 GB

Configuring Your Webserver

Info
epiKshare comes with its own epiKshare/.htaccess file. Because php-fpm can’t read PHP settings in .htaccess these settings must be set in the epiKshare/.user.ini file. Please contact an epiKshare tech representative for assistance.


Configuring PHP

If you don’t want to use the epiKshare .htaccess or .user.ini file, you may configure PHP instead. Make sure to comment out any lines .htaccess pertaining to upload size, if you entered any.

...

Please contact the epiKshare support to get assistance with this advanced setting.

Configuring upload limits within the GUI

If all prerequisites described in this documentation are in place an admin can change the upload limits on demand by using the File handling input box within the administrative backend of epiKshare.

...

Info
Setting Strong Directory Permissions might prevent write access to these files. As an admin you need to decide between the ability to use the input box and a more secure epiKshare installation where you need to manually modify the upload limits in the .htaccess and .user.ini files described above.

Configuring the Collaborative Documents App

The Documents application supports editing documents within epiKshare, without the need to launch an external application. The Documents app supports these features:

...

Supported file formats are .odt, .doc, and .docx. .odt is supported natively in epiKshare, and you must have LibreOffice or OpenOffice installed on the epiKshare server to convert .doc, and .docx documents.

Providing Default Files

You may distribute a set of default files and folders to all users by placing them in the epiKshare/core/skeleton directory on your epiKshare server. These files appear only to new users after their initial login, and existing users will not see files that are added to this directory after their first login. The files in the skeleton directory are copied into the users’ data directories, so they may change and delete the files without affecting the originals.They appear on the user’s epiKshare Files page just like any other files.

Configuring External Storage (GUI)

The External Storage Support application enables you to mount external storage services and devices as secondary epiKshare storage devices. You may also allow users to mount their own external storage services.

Enabling External Storage Support

The External storage support application is enabled on your Apps page.

Storage Configuration

To create a new external storage mount, select an available backend from the dropdown Add storage. Each backend has different required options, which are configured in the configuration fields.

...

Required fields are marked with a red border. When all required fields are filled, the storage is automatically saved. A green dot next to the storage row indicates the storage is ready for use. A red or yellow icon indicates that epiKshare could not connect to the external storage, so you need to re-check your configuration and network availability.

User and Group Permissions

A storage configured in a user’s Personal settings is available only to the user that created it. A storage configured in the Admin settings is available to all users by default, and it can be restricted to specific users and groups in the Available for field.

Mount Options

Hover your cursor to the right of any storage configuration to expose the settings button and trashcan. Click the trashcan to delete the mountpoint. The settings button allows you to configure each storage mount individually with the following options:

  • Encryption

  • Previews

  • Filesystem check frequency (Never, Once per direct access, every time the filesystem is used)

Using Self-Signed Certificates

When using self-signed certificates for external storage mounts the certificate must be imported into the personal settings of the user. Please contact the epiKshare support for more information.

Available storage backends

The following backends are provided by the external storages app. Other apps may provide their own backends, which are not listed here.

Amazon S3

To connect your Amazon S3 buckets to epiKshare, you will need:

...

Enable path style is usually not required (and is, in fact, incompatible with newer Amazon datacenters), but can be used with non-Amazon servers where the DNS infrastructure cannot be controlled. Ordinarily, requests will be made with http://bucket.hostname.domain/, but with path style enabled, requests are made with http://hostname.domain/bucket instead.

 

Dropbox

While Dropbox supports the newer OAuth 2.0, epiKshare uses OAuth 1.0, so you can safely ignore any references to OAuth 2.0 in the Dropbox configuration.

...

You must be logged into Dropbox, and when epiKshare successfully verifies your connection Dropbox will ask for verification to connect to your Dropbox account. Click Allow, and you’re done.

FTP/FTPS

To connect to an FTP server, you will need:

...

FTP uses the password authentication scheme.

Google Drive

epiKshare uses OAuth 2.0 to connect to Google Drive. This requires configuration through Google to get an app ID and app secret, as epiKshare registers itself as an app.

...

When you see the green light confirming a successful connection you’re finished.

Local

Local storages provide access to any directory on the epiKshare server. Since this is a significant security risk, Local storage can only be configured in the epiKshare admin settings. Non-admin users cannot create Local storage mounts.

...

In the Available for field enter the users or groups who have permission to access the mount. By default all users have access.

OpenStack Object Storage

OpenStack Object Storage is used to connect to an OpenStack Swift server. Two authentication mechanisms are available: one is the generic OpenStack mechanism, and the other is used exclusively for Rackspace, a provider of object storage that uses the OpenStack Swift protocol.

...

It may be necessary to specify a Service name or Region. The timeout of HTTP requests is set in the Request timeout field, in seconds.

epiKshare

An epiKshare storage is a specialized WebDAV storage, with optimizations for epiKshare-epiKshare communication. See the WebDAV documentation to learn how to configure an epiKshare external storage.

When filling in the URL field, use the path to the root of the epiKshare installation, rather than the path to the WebDAV endpoint. So, for a server at http://example.com/epiKshare, use http://example.com/epiKshare and not http://example.com/epiKshare/remote.php/webdav.

SFTP

epiKshare’s SFTP (FTP over an SSH tunnel) backend supports both password and public key authentication.

...

The default Remote Subfolder is the root directory (/) of the remote SFTP server, and you may enter any directory you wish.

SMB/CIFS

 epiKshare can connect to Windows file servers or other SMB-compatible servers with the SMB/CIFS backend.

...

Optionally, you can specify a Domain. This is useful in cases where the SMB server requires a domain and a username, and an advanced authentication mechanism like session credentials is used so that the username cannot be modified. This is concatenated with the username, so the backend gets domain\username

WebDAV

Use this backend to mount a directory from any WebDAV server, or another epiKshare server.

...

Info
Please note: A non-blocking or correctly configured SELinux setup is needed for these backends to work. Please refer to the SELinux Configuration.

 

Allow Users to Mount External Storage

Check Enable User External Storage to allow your users to mount their own external storage services, and check the backends you want to allow. Beware, as this allows a user to make potentially arbitrary connections to other services on your network!

Adding Files to External Storages

We recommend configuring the background job Webcron or Cron to enable epiKshare to automatically detect files added to your external storages.

...

Please contact an epiKshare tech representative to schedule a trigger to rescan the user’s files periodically (for example every 15 minutes), which includes the mounted external storage.

Configuration File

Storage mount configurations are stored in a JSON formatted file. Admin storages are stored in data/mount.json, while personal storages are stored in data/$user/mount.json. For more advanced use cases, including provisioning external storages from outside epiKshare, please contact the epiKshare support.

Using self-signed certificates

When using self-signed certificates for external storage mounts the certificate needs to be imported in the personal settings of the user. Please contact us to get more information.

Configuring Temporary Disk Space Needs

Not all external storage types are currently enabled for, or support streaming. Therefore epiKshare needs temporary space to buffer data for transfers. This can occur when there are many concurrent users transferring data with a higher volume over small bandwidth. epiKshare may need, in these cases, additional temporary space.

...

External storage list that uses direct file streaming:

External Storage Password Management

epiKshare handles passwords for external mounts differently than regular epiKshare user passwords.

...

You can protect your PHP session files using protections available in your filesystem. Stored credentials are always accessible to the epiKshare instance.

External Storage Authentication mechanisms

epiKshare storage backends accept one or more authentication schemes such as passwords, OAuth, or token-based, to name a few examples. Each authentication scheme may be implemented by multiple authentication mechanisms. Different mechanisms require different configuration parameters, depending on their behaviour.

Special Mechanisms

The None authentication mechanism requires no configuration parameters, and is used when a backend requires no authentication.

The Built-in authentication mechanism itself requires no configuration parameters, but is used as a placeholder for legacy storages that have not been migrated to the new system and do not take advantage of generic authentication mechanisms. The authentication parameters are provided directly by the backend.

Password-based Mechanisms

The Username and password mechanism requires a manually-defined username and password. These get passed directly to the backend.

The Session credentials mechanism uses the epiKshare login credentials of the user to connect to the storage. These are not stored anywhere on the server, but rather in the user session, giving increased security. The drawback is that sharing is disabled when this mechanism is in use, as epiKshare has no access to the storage credentials and so other users cannot use it.

Public-key Mechanisms

Currently only the RSA mechanism is implemented, where a public/private keypair is generated by epiKshare and the public half shown in the GUI. The keys are generated in the SSH format, and are currently 1024 bits in length. Keys can be regenerated with a button in the GUI.

OAuth

OAuth 1.0 and OAuth 2.0 are both implemented, but currently limited to the Dropbox and Google Drive backends respectively. These mechanisms require additional configuration at the service provider, where an app ID and app secret are provided and then entered into epiKshare. Then epiKshare can perform an authentication request, establishing the storage connection.

Encryption Configuration

The primary purpose of the epiKshare server-side encryption is to protect users’ files on remote storage, such as Dropbox and Google Drive, and to do it easily and seamlessly from within epiKshare.

...

Note also that SSL terminates at or before Apache on the epiKshare server, and all files will exist in an unencrypted state between the SSL connection termination and the epiKshare code that encrypts and decrypts files. This is also potentially exploitable by anyone with administrator access to your server.

Before Enabling Encryption

Info
titleWarning
Plan very carefully before enabling encryption because it is not reversible via the epiKshare Web interface. If you lose your encryption keys your files are not recoverable. Always have backups of your encryption keys stored in a safe location, and consider enabling all recovery options.

Enabling Encryption

epiKshare encryption consists of two parts. The base encryption system is enabled and disabled on your Admin page. First you must enable this, and then select an encryption module to load. Currently the only available encryption module is the epiKshare Default Encryption Module.

...

Return to your Admin page to see the epiKshare Default Encryption Module added to the module selector, and automatically selected. Now you must log out and then log back in to initialize your encryption keys.

Sharing Encrypted Files

After encryption is enabled your users must also log out and log back in to generate their personal encryption keys. They will see a yellow warning banner that says “Encryption App is enabled but your keys are not initialized, please log-out and log-in again.”

Share owners may need to re-share files after encryption is enabled; users trying to access the share will see a message advising them to ask the share owner to re-share the file with them. For individual shares, un-share and re-share the file. For group shares, share with any individuals who can’t access the share. This updates the encryption, and then the share owner can remove the individual shares.

 Encrypting External Mountpoints

You and your users can encrypt individual external mountpoints. You must have external storage enabled on your Admin page, and enabled for your users.

 

Enabling Users File Recovery Keys

If you lose your epiKshare password, then you lose access to your encrypted files. If one of your users loses their epiKshare password their files are unrecoverable. You cannot reset their password in the normal way; you’ll see a yellow banner warning “Please provide an admin recovery password, otherwise all user data will be lost”.

...

You may change your Recovery Key password.

 

Files Not Encrypted

Only the data in the files in data/user/files are encrypted, and not the filenames or folder structures. These files are never encrypted:

...

There may be other files that are not encrypted; only files that are exposed to third-party storage providers are guaranteed to be encrypted.

Encryption with LDAP and Other External User Back-ends

If you use an external user back-end, such as an LDAP or Samba server, and you change a user’s password on the back-end, the user will be prompted to change their epiKshare login to match on their next epiKshare login. The user will need both their old and new passwords to do this. If you have enabled the Recovery Key then you can change a user’s password in the epiKshare Users panel to match their back-end password, and then, of course, notify the user and give them their new password.

Transactional File Locking

epiKshare’s Transactional File Locking mechanism locks files to avoid file corruption during normal operation. It performs these functions:

...

To use a memcache with Transactional File Locking, you must install the Redis server and corresponding PHP module. Please contact the epiKshare support for assistance.

 Mimetype aliases

epiKshare allows administrators to specify aliases for mimetypes. This makes it possible to show more specific icons for certain mimetypes. Take as an example audio files. It is nicer if they show a nice audio icon instead of the default file icon.

By default epiKshare is distributed with config/mimetypealiases.dist.json. Administrators should not modify this file, as it will be replaced when epiKshare is updated. Please contact our tech team to learn more about introducing more mimetypes.

Troubleshooting

How can I find out if my MySQL/PostgreSQL server is reachable?

To check the server’s network availability, use the ping command on the server’s host name (db.server.com in this example):

...

For a more detailed check whether the access to the database server software itself works correctly, see the next question.

 

Operations

Advanced operation including monitoring and scaling across multiple machines.

Considerations on Monitoring

Large scale epiKshare deployments are typically installed as load balanced n-tier web applications. Successfully managing such an installation requires active monitoring of the application and supporting infrastructure components. The purpose of this section is to outline the components of epiKshare that need to be monitored, and provide guidance on what to look for in epiKshare in an enterprise installation.

epiKshare Deployment Architecture

Before discussing how to monitor epiKshare, it is important to understand the architecture of a typical epiKshare deployment. These monitoring best practices are developed based on the use of load balanced web servers, a clustered database running a distributed database storage engine, such as MySQL NDB, and a clustered filesystem, such as Red Hat Storage.

It is assumed that specific enterprise tools (monitoring, log management, etc) to monitor operations are available, and that epiKshare is simply a new target for these tools.

The Important Components of epiKshare

epiKshare is a PHP application that depends on a filesystem for file storage, and a database for storing user and file meta data, as well as some application specific information. While the loss of an app server or a node in the database or storage clusters should not bring the system down, knowing that this happened and resolving it is essential to keeping the service running efficiently. Therefore it is important to monitor the epiKshare servers, the Load Balancer, the Storage Cluster and the Database. This documentation starts with the epiKshare application and works out from there through the layers of infrastructure.

Status.php

epiKshare provides a very simple mechanism for determining if an application server is up and functioning – call the status.php file on each epiKshare server. This file can be found in the root epiKshare directory on the server, which by default is /epiKshare/status.php. If the server is functioning normally, the response looks something like this:

...

We recommend monitoring this file on each epiKshare application server to provide a basic check that the server is operating properly.

epiKshare.log

epiKshare also provides a built in logging function. If the epiKshare Enterprise Edition logging applications are enabled, this file will track user logins and shared file activity. If these logging applications are not enabled, this log file still tracks basic epiKshare health. Given the potential for this file to get quite large, the log file should be rotated on a daily basis, and given the importance of the error information in the log file, this should be integrated with an enterprise log manager.

Logfile entries that start with the keyword “Error” should be logged and reported to epiKshare support.

Apache

The apache error and access log should also be monitored. Significant spontaneous changes of the number of requests per second should also be monitored and looked into.

Database server

The load and general health of the database server or cluster has to be monitored also. All mysql vendors provide tools to monitor this.

Clustered Filesystem

The available space of the filesystem should be monitored to prevent a full epiKshare. This functionality is provided by the operating-system and/or the cluster filesystem vendor.

Load Balancer

The load balancer is monitoring the health of the application servers and is distributing the traffic in the optimal way. The application-servers should also be monitored to detect long lasting OS or hardware problems. Monitoring solutions like Nagios provide built in functionality to do this.

Bugs

If you think you have found a bug in epiKshare, please:

...

Info
If you can’t find a solution, please contact our epiKshare support team.

General Troubleshooting

epiKshare Logfiles

In a standard epiKshare installation the log level is set to Normal. To find any issues you need to raise the log level to Everything on your epiKshare Admin page. Please see Logging Configuration for more information on these log levels.

For JavaScript issues you will also need to view the javascript console. All major browsers have developer tools for viewing the console, and you usually access them by pressing F12. For Firefox we recommend to installing the Firebug extension.

Debugging Sync Issues

 

Info
titleWarning
The data directory on the server is exclusive to epiKshare and must not be modified manually.

...

https://example.org/epiKshare/remote.php/webdav

Common problems / error messages

Some common problems / error messages found in your logfiles as described above:

  • SQLSTATE[HY000] [1040] Too many connections -> You need to increase the connection limit of your database, please refer to the manual of your database for more information.

  • SQLSTATE[HY000]: General error: 5 database is locked -> You’re using SQLite which can’t handle a lot of parallel requests. Please consider converting to another database like described in Converting Database Type.

  • SQLSTATE[HY000]: General error: 2006 MySQL server has gone away -> The database request takes too long and therefore the MySQL server times out. Its also possible that the server is dropping a packet that is too large. Please refer to the manual of your database for how to raise the config options wait_timeout and/or max_allowed_packet.

  • SQLSTATE[HY000] [2002] No such file or directory -> There is a problem accessing your SQLite database file in your data directory (data/epiKshare.db). Please check the permissions of this folder/file or if it exists at all. If you’re using MySQL please start your database.

  • Connection closed / Operation cancelled -> This could be caused by wrong KeepAlive settings within your Apache config. Make sure that KeepAlive is set to On and also try to raise the limits of KeepAliveTimeout and MaxKeepAliveRequests.

  • No basic authentication headers were found -> There is (most probably) a mistake in the configuration. Please contact the epiKshare support for assistance.

Other issues

Some services like Cloudflare can cause issues by minimizing JavaScript and loading it only when needed. When having issues like a not working login button or creating new users make sure to disable such services first.

License Keys

Introduction

You’ll need to install a license key to use epiKshare 8. There are two types of license keys: one is a free 30-day trial key. The other is a full license key for customers.

Configuration

Once you get your license key, it needs to be installed via the Admin section of your epiKshare installation. Please login as an administrator and install the license in the License seciton of the Admin panel.

Configuring SharePoint Integration

Native SharePoint support has been added to the epiKshare as a secondary storage location for SharePoint 2007, 2010 and 2013. When this is enabled, users can access and sync all of their SharePoint content via epiKshare, whether in the desktop sync, mobile or Web interfaces. Updated files are bi-directionally synced automatically. SharePoint shares are created by the epiKshare admin, and optionally by any users who have SharePoint credentials.

...

  • Basic Auth

  • NTLM (Recomended)

Enabling the SharePoint Plugin

The SharePoint plugin is a native plugin, so the first step is to enter the Apps administration page and enable it.

...

Please see Connecting to SharePoint in the User Manual to learn how to use your new SharePoint connections.

Note

 

Info

Speed up load times by disabling file previews in config.php, because the previews are generated by downloading the remote files to a temp file. This means epiKshare will spend a lot of time creating previews for all of your SharePoint content. To disable file previews, please inform the epiKshare support to have the setting changed accordingly.

Troubleshooting

SharePoint unsharing is handled in the background via Cron. If you remove the sharing option from a Sharepoint mount, it will take a little time for the share to be removed, until the Cron job runs.

...

A user can’t update the credentials: Verify that the correct credentials are configured, and the correct type, either global or custom.

Installing and Configuring the Windows Network Drive App

The Windows Network Drive app creates a control panel on your Admin page for seamless mounting of SMB/CIFS file shares on epiKshare servers.

...

Files are synchronized bi-directionally, and you can create, upload, and delete files and folders. epiKshare server admins can create Windows Network Drive mounts, and optionally allow users to create their own personal Windows Network Drive mounts. The password for each mount is encrypted and stored in the epiKshare database, using a long random secret key stored in the epiKshare config. This allows epiKshare to access the shares when the users who own the mounts are not logged in.

Installation

Enable the Windows Network Drive app on your epiKshare Apps page.

Creating a New Share

When you create a new SMB share you need the login credentials for the share, the server address, the share name, and the folder you want to connect to.

...

Info
When you create a new mountpoint using Login credentials you must log out of epiKshare, and then log back in so you can access the share. You only have to do this the first time.

 

Personal SMB Mounts

Users create their own personal SMB mounts on their Personal pages. These are created the same way as Admincreated shares. Users have only two options for login credentials:

  • Personal Credentials.

  • Custom Credentials

User Management

Shibboleth Integration

Introduction

The epiKshare Shibboleth user backend application integrates epiKshare with a Shibboleth Service Provider (SP) and allows operations in federated and single-sign-on (SSO) infrastructures. Setting up Shibboleth has two big steps:

  1. Enable and configure the Apache Shibboleth module.

  2. Enable and configure the epiKshare Shibboleth app.

The Apache Shibboleth module

Please contact the epiKshare support to get assistance with activating the Apache Shibboleth module and integrating the SSO authentification.

WebDAV Support

Users of standard WebDAV clients can use an alternative WebDAV Url, for example https://cloud.example.com/remote.php/nonshib-webdav/ to log in with their username and password. The password is generated on the Personal settings page.

Known Limitations

Encryption

File encryption can only be used together with Shibboleth when the master key-based encryption is used because the per- user encryption requires the user’s password to unlock the private encryption key. Due to the nature of Shibboleth the user’s password is not known to the service provider.

Other Login Mechanisms

You can allow other login mechanisms (e.g. LDAP or epiKshare native) by creating a second Apache virtual host configuration. This second location is not protected by Shibboleth, and you can use your other epiKshare login mechanisms.

Session Timeout

Session timeout on Shibboleth is controlled by the IdP. It is not possible to have a session length longer than the length controlled by the IdP. In extreme cases this could result in re-login on mobile clients and desktop clients every hour.

The session timeout can be overridden in the service provider, but this requires a source code change of the Apache Shibboleth module. A patch can be provided by the epiKshare support team.

UID Considerations and Windows Network Drive compatability

When using user_shibboleth in Single sign-on only mode, together with user_ldap, both apps need to resolve to the same uid. user_shibboleth will do the authentication, and user_ldap will provide user details such as email and displayname. In the case of Active Directory, multiple attributes can be used as the uid. But they all have different implications to take into account:

...

Also be aware that using user_shibboleth in Autoprovision Users mode will not allow you to use SSO for additional user_ldap users, because uid collisions will be detected by user_ldap.

Enabling Anonymous Uploads with Files Drop

The Files Drop application allows anyone to upload files with the click of a button to the directory of your choosing, without needing a login, and they cannot see or change the contents of the directory. It is the perfect replacement for attaching large files to email, maintaining an FTP server, and commercial file-sharing services.

When files are uploaded to your Files Drop directory, you can manage them just like any other epiKshare share: you may share them, restrict access, edit, and delete them.

Setting Up the Files Drop App

Setting up Files Drop is a matter of a few clicks. First go to your Apps page and enable it.

...

On your Personal page you should now see a URL for your upload directory. Share this URL with anyone you want to allow uploads to your File Drop folder. Note that the maximum upload size in this example is 512MB. (The default epiKshare upload file size limit is 512MB, but it can be changed. Please refer to the upload file size limit configuration section.)

Using the Files Drop App

Uploading files via the Files Drop app is simple. Open your Web browser to the share URL created by epiKshare. Click the Click to upload file button. This opens a file picker, and you select the file or directory you want to upload.

When your upload is completed, you’ll see a confirmation message with the filenames.

Enterprise Logging

There are two enterprise logging apps available to epiKshare customers: Log file sharing and Log user actions. The Log file sharing app records the file sharing activity of your users, and Log user actions records user logins and logouts.

...

Click the Download logfile button to dump the plain text log, or open the logfile directly in a text editor. 

Content by Label
showLabelsfalse
max5
spacesED
showSpacefalse
sortmodified
reversetrue
typepage
cqllabel in ("epikshare","admin","manual") and type = "page" and space = "ED"
labelsepikshare admin manual

...