Windows Network Drive (WND)
- libsmbclient Issues
- Basic Setup for One ownCloud Server
- Password Options
- Reduce WND Notifier Memory Usage
- 3rd Party Software Examples
- Password Option Precedence
- Optimizing wnd:process-queue
- The File Serializer
- Usage Recommendations
- Interaction Between Listener and Windows Password Lockout
- Multiple Server Setup
- Basic Command Execution Examples
The External Storage: Windows Network Drives app creates a control panel in your Admin page for seamlessly integrating Windows and Samba/CIFS shared network drives as external storages.
Any Windows file share and Samba servers on Linux and other Unix-type operating systems use the SMB/CIFS file-sharing protocol. The files and directories on the SMB/CIFS server will be visible on your Files page just like your other ownCloud files and folders.
Compared to standard SMB access, WND has advanced features like:
User lockout prevention and password reset
More authentication mechanisms against the backend
Enhanced ACL support
Here is a brief description of the advanced features:
Depending on the Windows or Samba policy, the user could get locked out of his account if he enters a wrong password a number of times. The lockout prevention tries to avoid this from happening, by resetting the password if it is wrong. For the case of ownCloud’s standard SMB connector, the password won’t be reset. It could happen, that the user gets locked out of the file server.
Please see the details about the Enterprise-Only Authentication Options
WND has the ability to trigger change notifications to users based on changes for files and folders.
With enhanced ACL support, both SMB and WND evaluate the file attributes (whether the file is hidden or read-only) to decide what ownCloud permissions should the file or folder have in ownCloud. On top of this, WND can also evaluate the ACLs by using the "ocLdapPermissionManager" in the mount point configuration. This will bring more accurate permissions to ownCloud, specially if each user could have different permissions over the files in Windows.
Mounts to a Windows or Samba file server are labeled with a little four-pane Windows-style icon, and the left pane of your Files page includes a Windows Network Drive filter. Figure 1 shows a new Windows Network Drive share marked with red warning which indicates that ownCloud cannot connect to the share. The reason is that it may require the user to login, or it is not available, or there is an error in the configuration.
Files are synchronized bi-directionally, and you can create, upload, and delete files and folders. ownCloud server admins can create Windows Network Drive mounts and optionally allow users to set up their own personal Windows Network Drive mounts.
Depending on the authentication method, passwords for each mount are encrypted and stored in the ownCloud
database, using a long random secret key stored in
config.php. This allows ownCloud to access the shares
when the users who own the mounts are not logged in. This access will not work if the mount is session based, where passwords are not stored, and available only for the current active session.
Install the External Storage: Windows Network Drives app from the ownCloud Market App or ownCloud Marketplace. To make it work, a few dependencies have to be installed.
A Samba client. This is included in all Linux distributions. On Debian, Ubuntu, and other Debian derivatives it is called
smbclient. On SUSE, Red Hat, CentOS, and other Red Hat derivatives it is
php-smbclient(version 0.8.0+). It should be included in most Linux distributions. You can use eduardok/libsmbclient-php, if your distribution does not provide it.
stdbuf. These should be included in most Linux distributions.
To install and configure the necessary packages, see the Prepare Your Server section of the manual installation documentation.
|For more information on SMB/CIFS in ownCloud, refer to the Samba file server configuration documentation.|
If you encounter errors when using the WND app like
The Windows Network Drive Listener only supports version 1 of the SMB protocol (SMB1) with earlier Samba versions.
A Samba server, often a Microsoft Windows Server, can enforce the minimum and maximum protocol versions used by connecting clients. However, in light of the WannaCry ransomware attack, Microsoft patched Windows Server to only allow SMB2 as minimum protocol by default, as SMB1 is insecure.
The ownCloud windows network drive listener utilizes the SMB notification feature which works well with SMB1 in conjunction with most Samba versions. However, when the minimum protocol a server accepts is SMB2, ownCloud requires Samba 4.7.8+ (4.8+ etc.) to be able to properly work, as prior versions of Samba had a bug that broke this feature.
To enable external storage, as the ownCloud administrator go to. Tick the checkbox to enable external storage.
When you create a new WND share, you need three things:
The login credentials for the share
The server address, the share name; and
The folder you want to connect to
Treat all the parameters as being case-sensitive.
Although some parts of the app might work properly regardless of casing, other parts might have problems if the case is not respected.
Enter the ownCloud mount point for your new WND share. This must not be an existing folder.
Select your authentication method; See Enterprise-Only Authentication Options for complete information on the five available authentication methods.Figure 2. WND mountpoint and authorization credentials
Enter the address of the server that contains the WND share.
The Windows share name.
The root folder of the share. This is can be the subfolder name, or the
$uservariable for the user’s home directories. Note that the LDAP
Internal Username Attributemust be set to the
samaccountnamefor either the share or the root to work, and the user’s home directory needs to match the
samaccountname. (See User Authentication with LDAP.)
Select users or groups with access to the share. The default is all users.
Click the gear icon for additional mount options. Note, that previews are enabled by default, while sharing is not (see Figure 3). Sharing is not available for all authorization methods. For details please see the Enterprise-Only Authentication Options. When using large storages with many files, you may want to disable previews, because this can significantly increase performance.Figure 3. WND server, credentials, and additional mount options
Your changes are saved automatically.
|When you create a new mountpoint using login credentials (session based), you must log out of ownCloud and then log back in so you can access the share. You only have to do this the first time.|
Starting with version 1.0.1 of the Windows Network Drives App Access Control Lists (ACLs) are supported. To obtain the ACL information, two ACL providers can be selected:
On standard deployments, you don’t need to change anything. Just leave the field empty and the default
nullPermissionManager permission manager will be used.
Regardless of which provider you choose, an ownCloud administrator should run a files:scan, manually, after changing the configuration, to update the permissions correctly. Otherwise, the permissions shown by ownCloud might be incorrect.
|Permissions are only auto-updated if there has been a change in the files.|
Null Permission Manager is the default permission manager for ACLs and is used, if no other ACL
manager is specified. This is also the case, when no permission is explicitly set. If you want to retain
ownCloud’s current behaviour, then use this permission manager. When in effect, the Windows Network Drive
app uses the file’s attributes (e.g., read-only, and hidden), to determine how the user can interact with
the file. There are no usage restrictions.
The value to select for this provider is:
The ownCloud LDAP Permission Manager evaluates ACLs in files along with file attributes to determine the permissions. In order to evaluate the ACLs, it needs access to the user and group membership information of the target Windows or Samba server. Therefore it uses ownCloud’s LDAP Integration app for this.
|Both the Windows (or Samba) server and ownCloud’s LDAP Integration app must connect to the same Active Directory server so that ownCloud can retrieve the same user and group information.|
The use of this provider requires two key things:
An Active Directory server which contains the standard user and group information that can be used by the LDAP Integration app.
ownCloud’s LDAP Integration app to be correctly configured to retrieve user and group information from the same Active Directory / LDAP server as the one that the Windows or Samba server uses.
The ownCloud LDAP Integration app must configure the
Some groups, such as
The value to select for this provider is:
The SMB protocol supports registering for notifications of file changes on remote Windows SMB storage servers. Notifications are more efficient than polling for changes, as polling requires scanning the whole mounted SMB storage. While files changed through the ownCloud Web Interface or sync clients are automatically recognized by ownCloud, this recognitions are not possible when files are changed directly on remote SMB storage mounts. When using the listener, files changed on the SMB backend are recognized and a notification is stored in the database. The process-queue job reads these stored notifications and initiates further actions.
|The capability of the listener depends on the ability of the used SMB/CIFS storage backend to provide notifications. While Windows file servers have no limitations, some vendors may have restrictions. Please check these with your storage provider. It may be possible, that notifications for Samba only work for the target folder you’re listening to, but not for any sub structures. If you’re listening on the "/top" folder, you may not receive notifications for "/top/middle/bottom" folder. In this case, you have to setup listeners for every existing folder and also for any new folders that will be created. With Windows file servers, you will receive notifications for every file or subfolder inside the folder you’re listening to.|
The WND listener for ownCloud 10 includes two different commands that need to be executed:
This command listens to changes for each host and share configured and stores all notifications gathered in the database. It is intended to run this command as a service. The command requires the Windows/Samba account and the host/share the listener will listen to. The command does not produce any output by default, unless an error happens. Each stored notification will be further processed by the
wnd:process-queue and will removed from the database after processing.
You can increase the command’s verbosity by using
The simplest way, useful for initial testing is, to start the
wnd:listen process manually, as follows:
sudo -u www-data php occ wnd:listen <host> <share> <username>
The password is an optional parameter and you will be asked for it if you didn’t provide it as in the example above. In order to start
wnd:listen without any user interaction like as service, provide the password from a password file.
sudo -u www-data php occ wnd:listen <host> <share> <username> \ --password-file=/my/secret/password/file \ --password-trim
For additional options to provide the password, check Password Options
Note that the password must be in plain text inside the file. Neither spaces nor newline characters will be removed from the contents of the file by default, unless the
--password-trim option is added. The password file must be readable by the apache user (or www-data). Also make sure that the password file is outside of any directory handled by apache (web-readable) for security reasons. You may use the same location when using flock in Execution Serialization below.
You should be able to run any of those commands, and/or wrap them into a systemd service or any other
startup service, so that the
wnd:listen command is automatically started post booting.
This command processes the stored notifications for a given host and share. This process is intended to
be run periodically as a Cron job, or via a similar mechanism. The command will process the notifications
stored by the
wnd:listen process, showing only errors by default. If you need more information, increase
the verbosity by calling
As a simple example, you can check the following:
sudo -u www-data php occ wnd:process-queue <host> <share>
You can run that command, even if there are no notifications to be processed.
Depending on your requirements, you can wrap that command in a Cron job so it’s run every 5 minutes for example.
Create a service for
systemd following the instructions below that checks for processable notifications:
For each WND mount point distinguished by a SERVER - SHARE pair:
Create a file for each
owncloud-wnd-listen-SERVER-SHARE.serviceand locate it in
Password: For security reasons, create a file readable only by
www-dataand outside the directories handled by apache (let’s suppose in /opt/mypass). The file must contain only the password for the share. In this example our file is: "/opt/mypass". The listener will read the contents of the file and use them as the password for the account. This way, only root and the apache user should have access to the password.
--password-trimremoves blank characters from the password file added by 3rdparty software or other services.
[Unit] Description=ownCloud WND Listener for SERVER SHARE After=syslog.target After=network.target Requires=apache2.service [Service] User=www-data Group=www-data WorkingDirectory=/var/www/owncloud ExecStart=/usr/bin/php ./occ wnd:listen -vvv SERVER SHARE USER --password-file=/opt/mypass --password-trim Type=simple StandardOutput=journal StandardError=journal SyslogIdentifier=%n KillMode=process RestartSec=3 Restart=always [Install] WantedBy=multi-user.target
Run the following command, once for each created file:
sudo systemctl daemon-reload sudo systemctl enable owncloud-wnd-listen-SERVER-SHARE.service sudo systemctl start owncloud-wnd-listen-SERVER-SHARE.service
To list all systemd wnd listeners for ownCloud run the following command, assuming you use the naming convention described above:
systemctl list-units | grep owncloud-wnd-listen
Please re-run the following commands if you are changing the contents of a particular listener service:
sudo systemctl daemon-reload sudo systemctl restart owncloud-wnd-listen-SERVER-SHARE.service
For more information about configuring services for systemd, read How To Use Systemctl to Manage Systemd Services and Units
Create or add a
crontab file in
The commands must be strictly sequential. This can be done by using
crontabentry to run a script iterating over all
SERVER SHAREpairs with an appropriate
* * * * * sudo -u www-data /usr/bin/php /var/www/owncloud/occ wnd:process-queue <HOST> <SHARE>
Parallel runs of
wnd:process-queue might lead to a user lockout. The reason for this is that several
wnd:process-queue might use the same wrong password because it hasn’t been updated by the time they fetch it.
If you need to serialize the execution of the
wnd:process-queue, check the following example with
flock -n /opt/my-lock-file sudo -u www-data php occ wnd:process-queue <host> <share>
In that case, flock will try get the lock of that file and won’t run the command if it isn’t possible. For
our case, and considering that file isn’t being used by any other process, it will run only one
wnd:process-queue at a time. If someone tries to run the same command a second time while the previous
one is running, the second will fail and won’t be executed.
The lock file
/opt/my-lock-file itself will be created as an empty file by the
flock command if it does not yet exist, but after it has been created the lock file doesn’t change. Only an flock will be applied and removed. The file won’t be removed after the script completes.
You can use flock also in cron, see the example below:
* * * * * flock -n /opt/my-lock-file -c 'sudo -u www-data /usr/bin/php /var/www/owncloud/occ wnd:process-queue <HOST> <SHARE>'
Check flock’s documentation for details and more options.
From version 2.0.0 the Windows Network Drive app includes an extension of the Activity app. This extension will allow the app to send events to the Activity app so the users know what happened in the Windows Network Drive storage.
Please see Figure 4 how a notification can look like. In this example, one user accessing the same host/share has changed a file. Other users will now get a activity notification about this change.
This extension requires the following components:
wnd:listencommand set up and running in order to get the storage events
wnd:process-queuecommand running periodically (or manually) over the event queues generated by the
The Activity app enabled
For setting up the
wnd:process-queue commands, see their respective sections above.
This extension is disabled by default. This means that no activity will reach the users. In order to enable this extension, you can edit the
config/config.php file and add the following configuration:
'wnd.activity.registerExtension' => true,
|This configuration will affect all the WND mount points|
The events that will be shown to the users are based on what the
wnd:process-queue detects and changes in the ownCloud’s FS. Since the command includes some optimizations, some events might be inaccurate in some scenarios. For example, if multiple files are added in the same folder, there won’t be multiple "file added" events but only one "folder modified" in the parent folder.
The events are expected to reach only to the affected users. This filters out the users who cannot access the mount point, and also the users who do not have enough permissions in the Network Drive (Windows, Samba) to access that file.
As part of the Activity app configuration, each user can decide what events he wants to receive, and if he wants to receive them in the activity stream or via email.
Users who can access the Windows Network Drive storage via share won’t receive activity notifications by default. You can add the following configuration in the
config/config.php file to enable sending the activity notification to those users.
'wnd.activity.sendToSharees' => true,
If you encounter issues using Windows network drive, then try the following troubleshooting steps:
First check the connection to the share by using smbclient on the command line of the ownCloud server. Here is an example:
smbclient -U Username -L //Servername
Take the example of attempting to connect to the host MyHost, the share named
occ wnd:listen replacing user and password accordingly. Running the following command would work:
sudo -u www-data php occ wnd:listen MyHost MyData user password
|The command is case sensitive, and that it must match the information from the mount point configuration.|
If your Linux distribution ships with
libsmbclient 3.x, which is included in the Samba client, you may
need to set up the
HOME variable in Apache to prevent a segmentation fault. If you have
libsmbclient 4.1.6 and higher, it doesn’t seem to be an issue, so you won’t have to change your
variable. To set up the
HOME variable on Ubuntu, modify the
unset HOME export HOME=/var/www
In Red Hat/CentOS, modify the
/etc/sysconfig/httpd file and add the following line to set the HOME
variable in Apache:
By default, CentOS has activated SELinux, and the
httpd process can not make outgoing network connections.
This will cause problems with the
samba libraries. You’ll need to get around this
to make this work. First, check the status:
getsebool -a | grep httpd httpd_can_network_connect --> off
Then enable support for network connections:
setsebool -P httpd_can_network_connect 1
In openSUSE, modify the
Restart Apache, open your ownCloud Admin page and start creating SMB/CIFS mounts.
Go to the admin settings and set up the required WND mounts. Be aware though, that there are some limitations. These are:
ownCloud needs access to the Windows account password for the mounts to update the file cache properly. This means that "login credentials, saved in session" won’t work with the listener. ownCloud suggests to use "login credentials, saved in DB" as the best replacement instead.
$userplaceholder for the share name, such as
//host/$user/path/to/root, providing a share which is accessible per/user won’t work with the listener. This is because the listener won’t scale, as you’ll need to setup one listener per/share equals one listener per user. As a result, you’ll end up with too many listeners. An alternative is, to provide a common share for the users and use the
$userplaceholder in the root, such as
wnd:listenprocess if it’s not already started, ideally running it as a service. If it isn’t running, no notification are stored. The listener stores the notifications. Any change in the mount point configuration, such as adding or removing new mounts, and logins by new users, won’t affect the behavior, so there is no need to restart the listener in those cases.
In case you have several mount point configurations, note that each listener attaches to one host and share. If there are several mount configurations targeting different shares, you’ll need to spawn one listener for each. For example, if you have one configuration with
10.0.0.2/share1and another with
10.0.0.2/share2, you’ll need to spawn 2 listeners, one for the first configuration and another for the second.
wnd:process-queueperiodically, usually via a Cron job. The command processes all the stored notifications for a specific host and share. If you have several, you could set up several Cron jobs, one for each host and share with different intervals, depending on the load or update urgency. As a simple example, you could run the command every 2 minutes for one server and every 5 minutes for another.
As said, the command processes all the stored notifications, squeeze them and scan the resulting folders.
The process might crash if there are too many notifications, or if it has too many storages to update. The
--chunk-size option will help by making the command process all the notifications in buckets of that size.
On the one hand the memory usage is reduced, on the other hand there is more network activity. We recommend using the option with a value high enough to process a large number of notifications, but not so large to crash the process. Between 200 and 500 should be fine, and we’ll likely process all the notifications in one go.
There are several ways to supply a password:
Interactively in response to a password prompt.
sudo -u www-data php occ wnd:listen <host> <share> <username>
Sent as a parameter to the command.
sudo -u www-data php occ wnd:listen <host> <share> <username> <password>
Read from a file, using the
--password-fileswitch to specify the file to read from. Note, that the password must be in plain text inside the file, and neither spaces nor newline characters will be removed from the file by default, unless the
--pasword-trimoption is added. The password file must be readable by the apache user (or www-data)
sudo -u www-data php occ wnd:listen <host> <share> <username> \ --password-file=/my/secret/password/file
sudo -u www-data php occ wnd:listen <host> <share> <username> \ --password-file=/my/secret/password/file \ --password-trim
If you use the
--password-fileswitch, the entire contents of the file will be used for the password, so please be careful with newlines.
--password-filemake sure that the file is only readable by the apache / www-data user and inaccessible from the web. This prevents tampering or leaking of the information. The password won’t be leaked to any other user using
Using 3rd party software to store and fetch the password. When using this option, the 3rd party app needs to show the password as plaintext on standard output.
The WND in-memory notifier for password changes provides the ability to notify all affected WND storages to reset their passwords. This feature is intended to prevent a password lockout for the user in the backend. However, this functionality can consume a significant amount of memory. To disable it, add the following configuration to your
'wnd.in_memory_notifier.enable' => false,
|The password will be reset on the next request, regardless of the flag setting.|
cat /tmp/plainpass | sudo -u www-data php occ wnd:listen <host> <share> <username> --password-file=-
This provides a bit more security because the
/tmp/plainpass password should be owned by root and only
root should be able to read the file (0400 permissions); Apache, particularly, shouldn’t be able to read it.
It’s expected that root will be the one to run this command.
base64 -d /tmp/encodedpass | \ sudo -u www-data php occ wnd:listen <host> <share> <username> --password-file=-
Similar to the previous example, but this time the contents are encoded in Base64 format (there’s not much security, but it has additional obfuscation).
Third party password managers can also be integrated. The only requirement is that they have to provide the password in plain text somehow. If not, additional operations might be required to get the password as plain text and inject it in the listener.
As an example:
You can use "pass" as a password manager.
You can go through http://xmodulo.com/manage-passwords-command-line-linux.html to setup the keyring for whoever will fetch the password (probably root) and then use something like the following
pass the-password-name | sudo -u www-data php occ wnd:listen <host> <share> <username> --password-file=-
If both the argument and the option are passed, e.g.,
occ wnd:listen <host> <share> <username> <password> --password-file=/tmp/pass,
--password-file option will take precedence.
|Do not use this option if the process-queue is fast enough. The option has some drawbacks, specifically regarding password changes in the backend.|
wnd:process-queue creates all the storages that need to be updated from scratch. To do so, we need to
fetch all the users from all the backends (currently only the ones that have logged in at least once
because the others won’t have the storages that we’ll need updates).
To optimize this,
wnd:process-queue make use of two switches:
These serialize storages for later use, so that future executions don’t need to fetch the users, saving
precious time — especially for large organizations.
While the specific behavior will depend on the serializer implementation, the overall behavior can be simplified as follows:
If the serializer’s data source (such as a file, a database table, or some Redis keys) has storage data, it uses that data to create the storages; otherwise, it creates the storages from scratch.
After the storages are created, notifications are processed for the storages. If the storages have been created from scratch, those storages are written in the data source so that they can be read on the next run.
|It’s imperative to periodically clean up the data source to fetch fresh data, such as for new storages and updated passwords. There isn’t a generic command to do this from ownCloud, because it depends on the specific serializer type. Though this option could be provided at some point if requested.|
The file serializer is a serializer implementation that can be used with the
It requires an additional parameter where you can specify the location of the file containing the
There are several things you should know about this serializer:
The generated file contains the encrypted passwords for accessing the backend. This is necessary in order to avoid re-fetching the user information, when next accessing the storages.
The generated file is intended to be readable and writable only for the web server user. Other users shouldn’t have access to this file. Do not manually edit the file. You can remove the file if it contains obsolete information.
Only one file serializer should be used per server and share, as the serialized file has to be per server and share. Consider the following usage scenario:
If you have three shares:
10.0.10.20/share2, then you should use three different calls to
wnd:process-queue, changing the target file for the serializer for each one.
Since the serialized file has to be per server and share, the serialized file has some checks to prevent misuse. Specifically, if we detect you’re trying to read the storages for another server and share from the file, the contents of the file won’t be read and will fallback to creating the storage from scratch. At this point, we’ll then update the contents of that file with the new storage.
Doing so, though, creates unneeded competition, where several process-queue will compete for the serializer file. For example, let’s say that you have two process-queues targeting the same serializer file. After the first process creates the file the second process will notice that the file is no longer available. As a result, it will recreate the file with new content.
At this point the first process runs again and notices that the file isn’t available and recreate the file again. When this happens, the serializer file’s purpose isn’t fulfilled As a result, we recommend the use of a different file per server and share.
Windows supports password lockout policies. If one is enabled on the server where an ownCloud share is located, and a user fails to enter their password correctly several times, they may be locked out and unable to access the share.
This is a known issue
that prevents these two inter-operating correctly. Currently, the only viable solution is to ignore that
feature and use the
wnd:process-queue, without the serializer options.
Setups with several servers might have some difficulties in some scenarios:
wnd:listencomponent might be duplicated among several servers. This shouldn’t cause a problem, depending on the limitations of the underlying database engine. The supported database engines should be able to handle concurrent access and de-duplication.
wnd:process-queueshould also be able to run from any server, however limitations for concurrent executions still apply. As a result, you might need to serialized command execution of the
wnd:process-queueamong the servers (to avoid for the password lockout), which might not be possible or difficult to achieve. You might want to execute the command from just one specific server in this case.
wnd:process-queue+ serializer. First, check the above section to know the interactions with the password lockout. Right now, the only option you have to set it up is to store the target file in a common location for all the server. We might need to provide a specific serializer for this scenario (based on Redis or DB)
sudo -u www-data php occ `wnd:listen` host share username password sudo -u www-data php occ `wnd:process-queue` host share sudo -u www-data php occ `wnd:process-queue` host share -c 500 sudo -u www-data php occ `wnd:process-queue` host share -c 500 \ --serializer-type file \ --serializer-params file=/opt/oc/store sudo -u www-data php occ `wnd:process-queue` host2 share2 -c 500 \ --serializer-type File \ --serializer-params file=/opt/oc/store2
To set it up, make sure the listener is running as a system service:
sudo -u www-data php occ wnd:listen host share username password
Setup a Cron job or similar with something like the following two commands:
sudo -u www-data php occ wnd:process-queue host share -c 500 \ --serializer-type file \ --serializer-params file=/opt/oc/store1 sudo rm -f /opt/oc/store1 # With a different schedule
The first run will create the
/opt/oc/store1 with the serialized storages, the rest of the executions
will use that file. The second Cron job, the one removing the file, will force the
refresh the data.
It’s intended to be run in a different schedule, so there are several
executions of the
wnd:process-queue fetching the data from the file.
Note that the file can be removed manually at any time if it’s needed
(for example, the admin has reset some passwords, or has been notified
about password changing).