{{Version|7.8.0}}

= File Storages per user =

This document tries to outline and explain the new concept of having the possibility to specify file storages on a per user basis that is introduced with Open‐Xchange Server v7.8.0.

== The previous situation ==

Before the introduction of the file storages per user feature, it was only possible to specify the file storage association per context.
That file storage was used for all modules/functions that are supposed to store/retrieve files:
* Drive
* Thumbnails
* PIM attachments
* Signature attachments

File storages are registered and maintained in file store table held in configDb database. File storage obtains a unique identifier, a base URI and a size limitation.

For each context a file storage identifier is specified alongside with a context quota that defines how much space that context is allowed to occupy in assigned file storage. Thus the sum of all quotas from those contexts assigned to file storage must not exceed the file storage’s size.

[[Image:file_storage_picture1.png|One file storage per context|650px]]

== Motivation ==

The motivation is to differentiate between file storages for common context‐associated files and Drive file. Those Drive files may further reside in the common context‐associated storage, but it also possible to specify user‐associated file storages where Drive files are maintained. The association is determined based on a folder's creator/owner: The quota gets accounted to that user that created a folder (provided the user has a user‐associated file storage).

[[Image:file_storage_picture2.png|Differentiate|650px]]

That kind of separation allows different provisioning scenarios that an administrator possibly wants to achieve. With regard to Drive files it is now possible to define per context that:

* All Drive files reside in the file storage associated with the context, which is either automatically determined or explicitly set (through -F,--destination-store-id option) when creating a context. All Drive files (from users of that context) and all other file resources (Snippets, PIM attachments, ...) share the same quota usage and limit settings. The file storage associated with the context is called '''context file storage'''.
* Certain users are supposed to store their Drive files in their own file storage with individual quota settings different from the context file storage. All files created in Drive folders owned by such a user are then accounted to that user-associated file storage having their own quota usage and limitation. The user-associated file storage may be set on user creation as it is for context creation. The file storage associated with a user is called '''user file storage'''. Introducing a user file storage is suitable when an administrator wants to have user-sensitive quota settings for Drive files and/or wants to assign a different type of storage for Drive files uploaded by users; e.g. let seldom used/accessed file resources reside in context file storage, but let frequently, highly accessed Drive files reside in a better storage sink
* A certain user has his own (bigger) file storage for Drive files and other users of that context are supposed to use that file storage to share the quota usage and limitation specified for that file storage. A file storage owned by a user that is also used by other users is called '''master file storage'''.

Having that possibilities of separation for quota usage and limitation it is possible to apply a certain use case scenario to contexts; e.g.

* Slow mass storage vs. fast Drive storage setup
* OX Drive Stand‐Alone setup

When assigning dedicated file storage for Drive to a certain user, the user’s file occupation is no more accounted to the overall context in which that user resides, but gets accounted to a dedicated user quota. Such a user quota can be used for different sales strategies that include tracking the user’s file occupation.

To achieve the file storage association on a per user basis, the existing user table has been enhanced by file storage and quota information as it is for the context table. Moreover the filestore_usage table has also been enhanced by the capability to account storage occupation to a certain user

[[Image:file_storage_picture3.png|Enhancements|650px]]

In addition the user table has also been extended by filestore_owner column. That column is used to let a user’s file storage be combined with another user’s storage. This serves the scenario in which a grouped OX Drive Stand‐Alone setup is operated. Multiple users’ file occupation gets accounted to a master user account.

Furthermore Open‐Xchange allows changing the running setups at any time to adjust the file storage usages/associations according to possibly changing needs/requirements.

=== Note ===

Please note that with introducing the concept of having user-associated file storages, the output for "listfilestore" command-line tool changed. Since also a user can be accounted to a file storage's capacity, the output changed to be:

/opt/open-xchange/sbin/listfilestore -A oxadminmaster -P secret
id path size reserved used max-entities cur-entities
2 file:///var/opt/filestore 1000 300 0 5000 2

Hence, "maxctx" is replaced with "max-entities" and "curctx" is replaced with "cur-entities"

== Seamless integration and flexibility ==
The new more flexible approach fits seamlessly into existing context/file storage setups. Thus there is no need to change anything, unless demanded by administrator

=== The fall‐back setup ===

[[Image:file_storage_picture4.png|The fall-back setup|650px]]

Everything stays as is. There is a storage‐per‐context association and every file is held in that storage. There are no user‐specific file storage attributes set in user table.

=== Slow mass storage vs. fast file storage setup ===

[[Image:file_storage_picture5.png|Slow mass storage|650px]]

There are two storages available: a file‐based and an S3 storage (assuming that the S3 one would be faster). While the context has the file‐based storage set, users in that context do have individual name spaces in the S3 storage.

That way common files (PIM/Signature attachments, thumbnails) are stored to context‐ associated file‐based storage while Drive documents are stored in the individual user name spaces in the S3 storage. Every user is allowed to occupy up to 10GB of space in the S3 storage (this can be varied as well).

=== OX Drive Stand‐Alone – Single User ===

[[Image:file_storage_picture6.png|OX Drive Stand-Alone - Single User|650px]]

Again there two file storages. Again the file‐based one is assumed to serve the slow mass storage behavior while S3 is assumed to be the fast storage.

Context designated to the Single User scenario for OX Drive Stand‐Alone operation, do hold only one user that has its individual name space associated in the S3 storage.

Again common files (PIM/Signature attachments, thumbnails) are stored in the context‐ associated file‐based storage while Drive documents are stored in the individual user name spaces in the S3 storage of each context. Every Drive document accounts the user‐sensitive quota of the associated user.

=== OX Drive Stand‐Alone – Business Account ===

[[Image:file_storage_picture7.png|OX Drive Stand-Alone - Business Account|650px]]

There two different file storages as in the previous setups. Again the file‐based one is assumed to serve the slow mass storage behavior while S3 is assumed to be the fast storage.

For this setup users do not hold their own individual name space in the S3 storage, but all share the same name space of the master user in the S3 storage. Moreover there are no dedicated user quotas, but all Drive documents do account to the master user’s quota

== Extensions to provisioning command‐line tools ==

=== createuser ===

The existing createuser CLI is enhanced by the following options
‐q/‐‐quota The file storage quota in MB for associated user
‐f/‐‐filestore The identifier for the file storage.
‐o/‐‐owner The owner for the file storage. If no owner is given and f/filestore option is set, the user itself is taken as owner

=== changeuser ===

The existing changeuser CLI is enhanced by the following option
‐q/‐‐quota The file storage quota in MB for associated user

'''Note:''' Option ALLOW_CHANGING_QUOTA_IF_NO_FILESTORE_SET in file 'AdminUser.properties' controls if a user file storage is automatically enabled if the ‐q/‐‐quota option is given on a 'changeuser' invocation as an alternative to 'movecontextfilestore2user'. For users without a user file storage the 'changeuser' CLT needs to be called with a quota value different to unlimited (-1) and unlimited quota will only be enabled in case the user already has a user file storage.

=== movecontextfilestore2user ===

Move a user’s files from a context to an individual storage name space. 
Usage: movecontextfilestore2user

‐h,‐‐help Prints a help text
‐‐environment Show info about commandline environment
‐‐nonl Remove all newlines (\n) from output
‐i,‐‐userid <userid> | Id of the user
‐u,‐‐username <username> | Username of the user
‐A,‐‐adminuser <adminuser> ? Admin username
‐P,‐‐adminpass <adminpass> ? Admin password
‐c,‐‐contextid <contextid> | The id of the context
‐N,‐‐contextname <contextname> | context name
‐f,‐‐filestore <filestore> * The identifier for the file storage.
‐q,‐‐quota <quota> * The file storage quota in MB for associated user.

Entries marked with an asterisk (*) are mandatory.
Entries marked with an question mark (?) are mandatory depending on your configuration.
Entries marked with a pipe (|) are mandatory for one another which means that at least one of them must be set.

=== moveuserfilestore2context ===

The counterpart for the previous CLI. Move a user's files from his individual storage name space to the context storage name space. 
Usage: moveuserfilestore2context

‐h,‐‐help Prints a help text
‐‐environment Show info about commandline environment
‐‐nonl Remove all newlines (\n) from output
‐i,‐‐userid <userid> | Id of the user
‐u,‐‐username <username> | Username of the user
‐A,‐‐adminuser <adminuser> ? Admin username
‐P,‐‐adminpass <adminpass> ? Admin password
‐c,‐‐contextid <contextid> | The id of the context
‐N,‐‐contextname <contextname> | context name

Entries marked with an asterisk (*) are mandatory.
Entries marked with an question mark (?) are mandatory depending on your configuration.
Entries marked with a pipe (|) are mandatory for one another that means that at least one of them must be set.

=== moveuserfilestore2master ===
Move a user's files from his individual storage name space to the storage name space of specified master. 
Usage: moveuserfilestore2master

‐h,‐‐help Prints a help text
‐‐environment Show info about commandline environment
‐‐nonl Remove all newlines (\n) from output
‐i,‐‐userid <userid> | Id of the user
‐u,‐‐username <username> | Username of the user
‐A,‐‐adminuser <adminuser> ? Admin username
‐P,‐‐adminpass <adminpass> ? Admin password
‐c,‐‐contextid <contextid> | The id of the context
‐N,‐‐contextname <contextname> | context name
‐m,‐‐master <master> Master user id. If not set, the context administrator is assumed to be the master user.

Entries marked with an asterisk (*) are mandatory.
Entries marked with an question mark (?) are mandatory depending on your configuration.
Entries marked with a pipe (|) are mandatory for one another, which means that at least one of them, must be set.

=== movemasterfilestore2user ===
Move a user's files from a master account name space to an individual storage name space. 
Usage: movemasterfilestore2user

‐h,‐‐help Prints a help text
‐‐environment Show info about commandline environment
‐‐nonl Remove all newlines (\n) from output
‐i,‐‐userid <userid> | Id of the user
‐u,‐‐username <username> | Username of the user
‐A,‐‐adminuser <adminuser> ? Admin username
‐P,‐‐adminpass <adminpass> ? Admin password
‐c,‐‐contextid <contextid> | The id of the context
‐N,‐‐contextname <contextname> | context name
‐m,‐‐master <master> Master user id. If not set, the context administrator is assumed to be the master user.
‐f,‐‐filestore <filestore> * The identifier for the file storage.
‐q,‐‐quota <quota> * The file storage quota in MB for associated user.

Entries marked with an asterisk (*) are mandatory.
Entries marked with an question mark (?) are mandatory depending on your configuration.
Entries marked with a pipe (|) are mandatory for one another, which means that at least one of them, must be set.

=== Creating a user file storage ===

Having the extensions to command-line tools a user-associated file storage can be enabled:

* After using 'movecontextfilestore2user' command-line tool
* Using 'changeuser' command-line tool with quota and filestore options or only quota options and "ALLOW_CHANGING_QUOTA_IF_NO_FILESTORE_SET" set to "true" in 'AdminUser.properties' file
* By provisioning via 'createuser' command-line tool with quota and filestore options

== Useful command‐line tools ==

The following command‐line tools might be useful to get an overview

* 'listfilestore' to list available file storages that can be assigned to contexts/users
* 'listcontext' to get the quota limit specified per context or -1 if none
* 'listuser' to get the quota limit specified per user or -1 if none
* 'listuserfilestores' to get a listing of users that use their own user file storage

== FAQs ==

=== When is a user filestore enabled or when did a user has a own filestore? ===

A user filestore has an own filestore if a filestore is assigned to this user. This can either be done via the create and update clt's or via the movecontextfilestore2user clt.

=== When is which quota affected? ===

In case the user has no own filestore the quota of the context filestore is affected. In case the user has an own filestore or in case the user is a slave user of another users filestore the quota of this user filestore is affected.

=== How can a user check his quota usage? ===

The 'Quota' portal widget shows quota and usage.

=== How to change the filestore quota shown in the portal widget? ===

To change the quota one just has to use the changeuser or changecontext CLT with the --quota (-q) argument. E.g.:

changecontext -A adminmaster -P masterpassword -c -q 1024

=== How does quota work for public files? ===

The quota of the folder creator/owner is in charge for files other users put inside. This affects the quota for users having an own filestore

=== What happens with ownership of public files and folders when the creator/owner gets deleted? ===

This depends which argument is used during the delete operation. In the default case, the context admin is assigned as the owner. But it is also possible that the data is assigned to a different user or that the data is completed removed.

=== What happens in over quota scenarios by deleting users? ===

If the data is assigned to a different user the quota limit is ignored. But the user (inheriting deleted user's files) is supposed to clean existing files as any attempt to create a Drive file will fail due to over-quota

=== How to deal with quota issues for the context admin caused by public files? ===

If the quota is too limited for the context admin the data should be completely removed or assigned to a different user. E.g.:
deleteuser -A ctxadmin -P password -c -i --no-reassign

AppSuite:File Storages per User

2016-11-03T08:40:57Z

Thorben: /* Useful command‐line tools */

{{Version|7.8.0}}

= File Storages per user =

This document tries to outline and explain the new concept of having the possibility to specify file storages on a per user basis that is introduced with Open‐Xchange Server v7.8.0.

== The previous situation ==

Before the introduction of the file storages per user feature, it was only possible to specify the file storage association per context.
That file storage was used for all modules/functions that are supposed to store/retrieve files:
* Drive
* Thumbnails
* PIM attachments
* Signature attachments

File storages are registered and maintained in file store table held in configDb database. File storage obtains a unique identifier, a base URI and a size limitation.

For each context a file storage identifier is specified alongside with a context quota that defines how much space that context is allowed to occupy in assigned file storage. Thus the sum of all quotas from those contexts assigned to file storage must not exceed the file storage’s size.

[[Image:file_storage_picture1.png|One file storage per context|650px]]

== Motivation ==

The motivation is to differentiate between file storages for common context‐associated files and Drive file. Those Drive files may further reside in the common context‐associated storage, but it also possible to specify user‐associated file storages where Drive files are maintained. The association is determined based on a folder's creator/owner: The quota gets accounted to that user that created a folder (provided the user has a user‐associated file storage).

[[Image:file_storage_picture2.png|Differentiate|650px]]

That kind of separation allows different provisioning scenarios that an administrator possibly wants to achieve. With regard to Drive files it is now possible to define per context that:

* All Drive files reside in the file storage associated with the context, which is either automatically determined or explicitly set (through -F,--destination-store-id option) when creating a context. All Drive files (from users of that context) and all other file resources (Snippets, PIM attachments, ...) share the same quota usage and limit settings. The file storage associated with the context is called '''context file storage'''.
* Certain users are supposed to store their Drive files in their own file storage with individual quota settings different from the context file storage. All files created in Drive folders owned by such a user are then accounted to that user-associated file storage having their own quota usage and limitation. The user-associated file storage may be set on user creation as it is for context creation. The file storage associated with a user is called '''user file storage'''. Introducing a user file storage is suitable when an administrator wants to have user-sensitive quota settings for Drive files and/or wants to assign a different type of storage for Drive files uploaded by users; e.g. let seldom used/accessed file resources reside in context file storage, but let frequently, highly accessed Drive files reside in a better storage sink
* A certain user has his own (bigger) file storage for Drive files and other users of that context are supposed to use that file storage to share the quota usage and limitation specified for that file storage. A file storage owned by a user that is also used by other users is called '''master file storage'''.

Having that possibilities of separation for quota usage and limitation it is possible to apply a certain use case scenario to contexts; e.g.

* Slow mass storage vs. fast Drive storage setup
* OX Drive Stand‐Alone setup

When assigning dedicated file storage for Drive to a certain user, the user’s file occupation is no more accounted to the overall context in which that user resides, but gets accounted to a dedicated user quota. Such a user quota can be used for different sales strategies that include tracking the user’s file occupation.

To achieve the file storage association on a per user basis, the existing user table has been enhanced by file storage and quota information as it is for the context table. Moreover the filestore_usage table has also been enhanced by the capability to account storage occupation to a certain user

[[Image:file_storage_picture3.png|Enhancements|650px]]

In addition the user table has also been extended by filestore_owner column. That column is used to let a user’s file storage be combined with another user’s storage. This serves the scenario in which a grouped OX Drive Stand‐Alone setup is operated. Multiple users’ file occupation gets accounted to a master user account.

Furthermore Open‐Xchange allows changing the running setups at any time to adjust the file storage usages/associations according to possibly changing needs/requirements.

=== Note ===

Please note that with introducing the concept of having user-associated file storages, the output for "listfilestore" command-line tool changed. Since also a user can be accounted to a file storage's capacity, the output changed to be:

/opt/open-xchange/sbin/listfilestore -A oxadminmaster -P secret
id path size reserved used max-entities cur-entities
2 file:///var/opt/filestore 1000 300 0 5000 2

Hence, "maxctx" is replaced with "max-entities" and "curctx" is replaced with "cur-entities"

== Seamless integration and flexibility ==
The new more flexible approach fits seamlessly into existing context/file storage setups. Thus there is no need to change anything, unless demanded by administrator

=== The fall‐back setup ===

[[Image:file_storage_picture4.png|The fall-back setup|650px]]

Everything stays as is. There is a storage‐per‐context association and every file is held in that storage. There are no user‐specific file storage attributes set in user table.

=== Slow mass storage vs. fast file storage setup ===

[[Image:file_storage_picture5.png|Slow mass storage|650px]]

There are two storages available: a file‐based and an S3 storage (assuming that the S3 one would be faster). While the context has the file‐based storage set, users in that context do have individual name spaces in the S3 storage.

That way common files (PIM/Signature attachments, thumbnails) are stored to context‐ associated file‐based storage while Drive documents are stored in the individual user name spaces in the S3 storage. Every user is allowed to occupy up to 10GB of space in the S3 storage (this can be varied as well).

=== OX Drive Stand‐Alone – Single User ===

[[Image:file_storage_picture6.png|OX Drive Stand-Alone - Single User|650px]]

Again there two file storages. Again the file‐based one is assumed to serve the slow mass storage behavior while S3 is assumed to be the fast storage.

Context designated to the Single User scenario for OX Drive Stand‐Alone operation, do hold only one user that has its individual name space associated in the S3 storage.

Again common files (PIM/Signature attachments, thumbnails) are stored in the context‐ associated file‐based storage while Drive documents are stored in the individual user name spaces in the S3 storage of each context. Every Drive document accounts the user‐sensitive quota of the associated user.

=== OX Drive Stand‐Alone – Business Account ===

[[Image:file_storage_picture7.png|OX Drive Stand-Alone - Business Account|650px]]

There two different file storages as in the previous setups. Again the file‐based one is assumed to serve the slow mass storage behavior while S3 is assumed to be the fast storage.

For this setup users do not hold their own individual name space in the S3 storage, but all share the same name space of the master user in the S3 storage. Moreover there are no dedicated user quotas, but all Drive documents do account to the master user’s quota

== Extensions to provisioning command‐line tools ==

=== createuser ===

The existing createuser CLI is enhanced by the following options
‐q/‐‐quota The file storage quota in MB for associated user
‐f/‐‐filestore The identifier for the file storage.
‐o/‐‐owner The owner for the file storage. If no owner is given and f/filestore option is set, the user itself is taken as owner

=== changeuser ===

The existing changeuser CLI is enhanced by the following option
‐q/‐‐quota The file storage quota in MB for associated user

'''Note:''' Option ALLOW_CHANGING_QUOTA_IF_NO_FILESTORE_SET in file 'AdminUser.properties' controls if a user file storage is automatically enabled if the ‐q/‐‐quota option is given on a 'changeuser' invocation as an alternative to 'movecontextfilestore2user'. For users without a user file storage the 'changeuser' CLT needs to be called with a quota value different to unlimited (-1) and unlimited quota will only be enabled in case the user already has a user file storage.

=== movecontextfilestore2user ===

Move a user’s files from a context to an individual storage name space. 
Usage: movecontextfilestore2user

‐h,‐‐help Prints a help text
‐‐environment Show info about commandline environment
‐‐nonl Remove all newlines (\n) from output
‐i,‐‐userid <userid> | Id of the user
‐u,‐‐username <username> | Username of the user
‐A,‐‐adminuser <adminuser> ? Admin username
‐P,‐‐adminpass <adminpass> ? Admin password
‐c,‐‐contextid <contextid> | The id of the context
‐N,‐‐contextname <contextname> | context name
‐f,‐‐filestore <filestore> * The identifier for the file storage.
‐q,‐‐quota <quota> * The file storage quota in MB for associated user.

Entries marked with an asterisk (*) are mandatory.
Entries marked with an question mark (?) are mandatory depending on your configuration.
Entries marked with a pipe (|) are mandatory for one another which means that at least one of them must be set.

=== moveuserfilestore2context ===

The counterpart for the previous CLI. Move a user's files from his individual storage name space to the context storage name space. 
Usage: moveuserfilestore2context

‐h,‐‐help Prints a help text
‐‐environment Show info about commandline environment
‐‐nonl Remove all newlines (\n) from output
‐i,‐‐userid <userid> | Id of the user
‐u,‐‐username <username> | Username of the user
‐A,‐‐adminuser <adminuser> ? Admin username
‐P,‐‐adminpass <adminpass> ? Admin password
‐c,‐‐contextid <contextid> | The id of the context
‐N,‐‐contextname <contextname> | context name

Entries marked with an asterisk (*) are mandatory.
Entries marked with an question mark (?) are mandatory depending on your configuration.
Entries marked with a pipe (|) are mandatory for one another that means that at least one of them must be set.

=== moveuserfilestore2master ===
Move a user's files from his individual storage name space to the storage name space of specified master. 
Usage: moveuserfilestore2master

‐h,‐‐help Prints a help text
‐‐environment Show info about commandline environment
‐‐nonl Remove all newlines (\n) from output
‐i,‐‐userid <userid> | Id of the user
‐u,‐‐username <username> | Username of the user
‐A,‐‐adminuser <adminuser> ? Admin username
‐P,‐‐adminpass <adminpass> ? Admin password
‐c,‐‐contextid <contextid> | The id of the context
‐N,‐‐contextname <contextname> | context name
‐m,‐‐master <master> Master user id. If not set, the context administrator is assumed to be the master user.

Entries marked with an asterisk (*) are mandatory.
Entries marked with an question mark (?) are mandatory depending on your configuration.
Entries marked with a pipe (|) are mandatory for one another, which means that at least one of them, must be set.

=== movemasterfilestore2user ===
Move a user's files from a master account name space to an individual storage name space. 
Usage: movemasterfilestore2user

‐h,‐‐help Prints a help text
‐‐environment Show info about commandline environment
‐‐nonl Remove all newlines (\n) from output
‐i,‐‐userid <userid> | Id of the user
‐u,‐‐username <username> | Username of the user
‐A,‐‐adminuser <adminuser> ? Admin username
‐P,‐‐adminpass <adminpass> ? Admin password
‐c,‐‐contextid <contextid> | The id of the context
‐N,‐‐contextname <contextname> | context name
‐m,‐‐master <master> Master user id. If not set, the context administrator is assumed to be the master user.
‐f,‐‐filestore <filestore> * The identifier for the file storage.
‐q,‐‐quota <quota> * The file storage quota in MB for associated user.

Entries marked with an asterisk (*) are mandatory.
Entries marked with an question mark (?) are mandatory depending on your configuration.
Entries marked with a pipe (|) are mandatory for one another, which means that at least one of them, must be set.

=== Creating a user file storage ===

Having the extensions to command-line tools a user-associated file storage can be enabled:

* After using 'movecontextfilestore2user' command-line tool
* Using 'changeuser' command-line tool with quota and filestore options or only quota options and "ALLOW_CHANGING_QUOTA_IF_NO_FILESTORE_SET" set to "true" in 'AdminUser.properties' file
* By provisioning via 'createuser' command-line tool with quota and filestore options

== Useful command‐line tools ==

The following command‐line tools might be useful to get an overview

* 'listfilestore' to list available file storages that can be assigned to contexts/users
* 'listcontext' to get the quota limit specified per context or -1 if none
* 'listuser' to get the quota limit specified per user or -1 if none
* 'listuserfilestores' to get a listing of users that use their own user file storage

== FAQs ==

=== When is a user filestore enabled or when did a user has a own filestore? ===

A user filestore has an own filestore if a filestore is assigned to this user. This can either be done via the create and update clt's or via the movecontextfilestore2user clt.

=== When is which quota affected? ===

In case the user has no own filestore the quota of the context filestore is affected. In case the user has an own filestore or in case the user is a slave user of another users filestore the quota of this user filestore is affected.

=== How can a user check his quota usage? ===

The 'Quota' portal widget shows quota and usage.

=== How to change the filestore quota shown in the portal widget? ===

To change the quota one just has to use the changeuser or changecontext CLT with the --quota (-q) argument. E.g.:

changecontext -A adminmaster -P masterpassword -c -q 1024

=== How does quota work for public files? ===

The quota of the folder creator/owner is in charge for files other users put inside. This affects the quota for users having an own filestore

=== What happens with ownership of public files and folders when the creator/owner gets deleted? ===

This depends which argument is used during the delete operation. In the default case, the context admin is assigned as the owner. But it is also possible that the data is assigned to a different user or that the data is completed removed.

=== What happens in over quota scenarios by deleting users? ===

If the data is assigned to a different user the quota limit is ignored.

=== How to deal with quota issues for the context admin caused by public files? ===

If the quota is too limited for the context admin the data should be completely removed or assigned to a different user. E.g.:
deleteuser -A ctxadmin -P password -c -i --no-reassign

AppSuite:File Storages per User

2016-11-03T08:36:41Z

Thorben: /* Useful command‐line tools */

AppSuite:File Storages per User

2016-11-03T08:36:11Z

Thorben: /* Extensions to provisioning command‐line tools */

{{Version|7.8.0}}

= File Storages per user =

This document tries to outline and explain the new concept of having the possibility to specify file storages on a per user basis that is introduced with Open‐Xchange Server v7.8.0.

== The previous situation ==

Before the introduction of the file storages per user feature, it was only possible to specify the file storage association per context.
That file storage was used for all modules/functions that are supposed to store/retrieve files:
* Drive
* Thumbnails
* PIM attachments
* Signature attachments

File storages are registered and maintained in file store table held in configDb database. File storage obtains a unique identifier, a base URI and a size limitation.

For each context a file storage identifier is specified alongside with a context quota that defines how much space that context is allowed to occupy in assigned file storage. Thus the sum of all quotas from those contexts assigned to file storage must not exceed the file storage’s size.

[[Image:file_storage_picture1.png|One file storage per context|650px]]

== Motivation ==

The motivation is to differentiate between file storages for common context‐associated files and Drive file. Those Drive files may further reside in the common context‐associated storage, but it also possible to specify user‐associated file storages where Drive files are maintained. The association is determined based on a folder's creator/owner: The quota gets accounted to that user that created a folder (provided the user has a user‐associated file storage).

[[Image:file_storage_picture2.png|Differentiate|650px]]

That kind of separation allows different provisioning scenarios that an administrator possibly wants to achieve. With regard to Drive files it is now possible to define per context that:

* All Drive files reside in the file storage associated with the context, which is either automatically determined or explicitly set (through -F,--destination-store-id option) when creating a context. All Drive files (from users of that context) and all other file resources (Snippets, PIM attachments, ...) share the same quota usage and limit settings. The file storage associated with the context is called '''context file storage'''.
* Certain users are supposed to store their Drive files in their own file storage with individual quota settings different from the context file storage. All files created in Drive folders owned by such a user are then accounted to that user-associated file storage having their own quota usage and limitation. The user-associated file storage may be set on user creation as it is for context creation. The file storage associated with a user is called '''user file storage'''. Introducing a user file storage is suitable when an administrator wants to have user-sensitive quota settings for Drive files and/or wants to assign a different type of storage for Drive files uploaded by users; e.g. let seldom used/accessed file resources reside in context file storage, but let frequently, highly accessed Drive files reside in a better storage sink
* A certain user has his own (bigger) file storage for Drive files and other users of that context are supposed to use that file storage to share the quota usage and limitation specified for that file storage. A file storage owned by a user that is also used by other users is called '''master file storage'''.

Having that possibilities of separation for quota usage and limitation it is possible to apply a certain use case scenario to contexts; e.g.

* Slow mass storage vs. fast Drive storage setup
* OX Drive Stand‐Alone setup

When assigning dedicated file storage for Drive to a certain user, the user’s file occupation is no more accounted to the overall context in which that user resides, but gets accounted to a dedicated user quota. Such a user quota can be used for different sales strategies that include tracking the user’s file occupation.

To achieve the file storage association on a per user basis, the existing user table has been enhanced by file storage and quota information as it is for the context table. Moreover the filestore_usage table has also been enhanced by the capability to account storage occupation to a certain user

[[Image:file_storage_picture3.png|Enhancements|650px]]

In addition the user table has also been extended by filestore_owner column. That column is used to let a user’s file storage be combined with another user’s storage. This serves the scenario in which a grouped OX Drive Stand‐Alone setup is operated. Multiple users’ file occupation gets accounted to a master user account.

Furthermore Open‐Xchange allows changing the running setups at any time to adjust the file storage usages/associations according to possibly changing needs/requirements.

=== Note ===

Please note that with introducing the concept of having user-associated file storages, the output for "listfilestore" command-line tool changed. Since also a user can be accounted to a file storage's capacity, the output changed to be:

/opt/open-xchange/sbin/listfilestore -A oxadminmaster -P secret
id path size reserved used max-entities cur-entities
2 file:///var/opt/filestore 1000 300 0 5000 2

Hence, "maxctx" is replaced with "max-entities" and "curctx" is replaced with "cur-entities"

== Seamless integration and flexibility ==
The new more flexible approach fits seamlessly into existing context/file storage setups. Thus there is no need to change anything, unless demanded by administrator

=== The fall‐back setup ===

[[Image:file_storage_picture4.png|The fall-back setup|650px]]

Everything stays as is. There is a storage‐per‐context association and every file is held in that storage. There are no user‐specific file storage attributes set in user table.

=== Slow mass storage vs. fast file storage setup ===

[[Image:file_storage_picture5.png|Slow mass storage|650px]]

There are two storages available: a file‐based and an S3 storage (assuming that the S3 one would be faster). While the context has the file‐based storage set, users in that context do have individual name spaces in the S3 storage.

That way common files (PIM/Signature attachments, thumbnails) are stored to context‐ associated file‐based storage while Drive documents are stored in the individual user name spaces in the S3 storage. Every user is allowed to occupy up to 10GB of space in the S3 storage (this can be varied as well).

=== OX Drive Stand‐Alone – Single User ===

[[Image:file_storage_picture6.png|OX Drive Stand-Alone - Single User|650px]]

Again there two file storages. Again the file‐based one is assumed to serve the slow mass storage behavior while S3 is assumed to be the fast storage.

Context designated to the Single User scenario for OX Drive Stand‐Alone operation, do hold only one user that has its individual name space associated in the S3 storage.

Again common files (PIM/Signature attachments, thumbnails) are stored in the context‐ associated file‐based storage while Drive documents are stored in the individual user name spaces in the S3 storage of each context. Every Drive document accounts the user‐sensitive quota of the associated user.

=== OX Drive Stand‐Alone – Business Account ===

[[Image:file_storage_picture7.png|OX Drive Stand-Alone - Business Account|650px]]

There two different file storages as in the previous setups. Again the file‐based one is assumed to serve the slow mass storage behavior while S3 is assumed to be the fast storage.

For this setup users do not hold their own individual name space in the S3 storage, but all share the same name space of the master user in the S3 storage. Moreover there are no dedicated user quotas, but all Drive documents do account to the master user’s quota

== Extensions to provisioning command‐line tools ==

=== createuser ===

The existing createuser CLI is enhanced by the following options
‐q/‐‐quota The file storage quota in MB for associated user
‐f/‐‐filestore The identifier for the file storage.
‐o/‐‐owner The owner for the file storage. If no owner is given and f/filestore option is set, the user itself is taken as owner

=== changeuser ===

The existing changeuser CLI is enhanced by the following option
‐q/‐‐quota The file storage quota in MB for associated user

'''Note:''' Option ALLOW_CHANGING_QUOTA_IF_NO_FILESTORE_SET in file 'AdminUser.properties' controls if a user file storage is automatically enabled if the ‐q/‐‐quota option is given on a 'changeuser' invocation as an alternative to 'movecontextfilestore2user'. For users without a user file storage the 'changeuser' CLT needs to be called with a quota value different to unlimited (-1) and unlimited quota will only be enabled in case the user already has a user file storage.

=== movecontextfilestore2user ===

Move a user’s files from a context to an individual storage name space. 
Usage: movecontextfilestore2user

‐h,‐‐help Prints a help text
‐‐environment Show info about commandline environment
‐‐nonl Remove all newlines (\n) from output
‐i,‐‐userid <userid> | Id of the user
‐u,‐‐username <username> | Username of the user
‐A,‐‐adminuser <adminuser> ? Admin username
‐P,‐‐adminpass <adminpass> ? Admin password
‐c,‐‐contextid <contextid> | The id of the context
‐N,‐‐contextname <contextname> | context name
‐f,‐‐filestore <filestore> * The identifier for the file storage.
‐q,‐‐quota <quota> * The file storage quota in MB for associated user.

Entries marked with an asterisk (*) are mandatory.
Entries marked with an question mark (?) are mandatory depending on your configuration.
Entries marked with a pipe (|) are mandatory for one another which means that at least one of them must be set.

=== moveuserfilestore2context ===

The counterpart for the previous CLI. Move a user's files from his individual storage name space to the context storage name space. 
Usage: moveuserfilestore2context

‐h,‐‐help Prints a help text
‐‐environment Show info about commandline environment
‐‐nonl Remove all newlines (\n) from output
‐i,‐‐userid <userid> | Id of the user
‐u,‐‐username <username> | Username of the user
‐A,‐‐adminuser <adminuser> ? Admin username
‐P,‐‐adminpass <adminpass> ? Admin password
‐c,‐‐contextid <contextid> | The id of the context
‐N,‐‐contextname <contextname> | context name

Entries marked with an asterisk (*) are mandatory.
Entries marked with an question mark (?) are mandatory depending on your configuration.
Entries marked with a pipe (|) are mandatory for one another that means that at least one of them must be set.

=== moveuserfilestore2master ===
Move a user's files from his individual storage name space to the storage name space of specified master. 
Usage: moveuserfilestore2master

‐h,‐‐help Prints a help text
‐‐environment Show info about commandline environment
‐‐nonl Remove all newlines (\n) from output
‐i,‐‐userid <userid> | Id of the user
‐u,‐‐username <username> | Username of the user
‐A,‐‐adminuser <adminuser> ? Admin username
‐P,‐‐adminpass <adminpass> ? Admin password
‐c,‐‐contextid <contextid> | The id of the context
‐N,‐‐contextname <contextname> | context name
‐m,‐‐master <master> Master user id. If not set, the context administrator is assumed to be the master user.

Entries marked with an asterisk (*) are mandatory.
Entries marked with an question mark (?) are mandatory depending on your configuration.
Entries marked with a pipe (|) are mandatory for one another, which means that at least one of them, must be set.

=== movemasterfilestore2user ===
Move a user's files from a master account name space to an individual storage name space. 
Usage: movemasterfilestore2user

‐h,‐‐help Prints a help text
‐‐environment Show info about commandline environment
‐‐nonl Remove all newlines (\n) from output
‐i,‐‐userid <userid> | Id of the user
‐u,‐‐username <username> | Username of the user
‐A,‐‐adminuser <adminuser> ? Admin username
‐P,‐‐adminpass <adminpass> ? Admin password
‐c,‐‐contextid <contextid> | The id of the context
‐N,‐‐contextname <contextname> | context name
‐m,‐‐master <master> Master user id. If not set, the context administrator is assumed to be the master user.
‐f,‐‐filestore <filestore> * The identifier for the file storage.
‐q,‐‐quota <quota> * The file storage quota in MB for associated user.

Entries marked with an asterisk (*) are mandatory.
Entries marked with an question mark (?) are mandatory depending on your configuration.
Entries marked with a pipe (|) are mandatory for one another, which means that at least one of them, must be set.

=== Creating a user file storage ===

Having the extensions to command-line tools a user-associated file storage can be enabled:

* After using 'movecontextfilestore2user' command-line tool
* Using 'changeuser' command-line tool with quota and filestore options or only quota options and "ALLOW_CHANGING_QUOTA_IF_NO_FILESTORE_SET" set to "true" in 'AdminUser.properties' file
* By provisioning via 'createuser' command-line tool with quota and filestore options

== Useful command‐line tools ==

The following command‐line tools might be useful to get an overview

* listfilestore to list available file storages that can be assigned to contexts/users
* listcontext to get the quota limit specified per context or -1 if none
* listuser to get the quota limit specified per user or -1 if none
* listuserfilestores to get a listing of users that use their own user file storage

AppSuite:File Storages per User

2016-11-03T08:31:51Z

Thorben: /* Extensions to provisioning command‐line tools */

{{Version|7.8.0}}

= File Storages per user =

This document tries to outline and explain the new concept of having the possibility to specify file storages on a per user basis that is introduced with Open‐Xchange Server v7.8.0.

== The previous situation ==

Before the introduction of the file storages per user feature, it was only possible to specify the file storage association per context.
That file storage was used for all modules/functions that are supposed to store/retrieve files:
* Drive
* Thumbnails
* PIM attachments
* Signature attachments

File storages are registered and maintained in file store table held in configDb database. File storage obtains a unique identifier, a base URI and a size limitation.

For each context a file storage identifier is specified alongside with a context quota that defines how much space that context is allowed to occupy in assigned file storage. Thus the sum of all quotas from those contexts assigned to file storage must not exceed the file storage’s size.

[[Image:file_storage_picture1.png|One file storage per context|650px]]

== Motivation ==

The motivation is to differentiate between file storages for common context‐associated files and Drive file. Those Drive files may further reside in the common context‐associated storage, but it also possible to specify user‐associated file storages where Drive files are maintained. The association is determined based on a folder's creator/owner: The quota gets accounted to that user that created a folder (provided the user has a user‐associated file storage).

[[Image:file_storage_picture2.png|Differentiate|650px]]

That kind of separation allows different provisioning scenarios that an administrator possibly wants to achieve. With regard to Drive files it is now possible to define per context that:

* All Drive files reside in the file storage associated with the context, which is either automatically determined or explicitly set (through -F,--destination-store-id option) when creating a context. All Drive files (from users of that context) and all other file resources (Snippets, PIM attachments, ...) share the same quota usage and limit settings. The file storage associated with the context is called '''context file storage'''.
* Certain users are supposed to store their Drive files in their own file storage with individual quota settings different from the context file storage. All files created in Drive folders owned by such a user are then accounted to that user-associated file storage having their own quota usage and limitation. The user-associated file storage may be set on user creation as it is for context creation. The file storage associated with a user is called '''user file storage'''. Introducing a user file storage is suitable when an administrator wants to have user-sensitive quota settings for Drive files and/or wants to assign a different type of storage for Drive files uploaded by users; e.g. let seldom used/accessed file resources reside in context file storage, but let frequently, highly accessed Drive files reside in a better storage sink
* A certain user has his own (bigger) file storage for Drive files and other users of that context are supposed to use that file storage to share the quota usage and limitation specified for that file storage. A file storage owned by a user that is also used by other users is called '''master file storage'''.

Having that possibilities of separation for quota usage and limitation it is possible to apply a certain use case scenario to contexts; e.g.

* Slow mass storage vs. fast Drive storage setup
* OX Drive Stand‐Alone setup

When assigning dedicated file storage for Drive to a certain user, the user’s file occupation is no more accounted to the overall context in which that user resides, but gets accounted to a dedicated user quota. Such a user quota can be used for different sales strategies that include tracking the user’s file occupation.

To achieve the file storage association on a per user basis, the existing user table has been enhanced by file storage and quota information as it is for the context table. Moreover the filestore_usage table has also been enhanced by the capability to account storage occupation to a certain user

[[Image:file_storage_picture3.png|Enhancements|650px]]

In addition the user table has also been extended by filestore_owner column. That column is used to let a user’s file storage be combined with another user’s storage. This serves the scenario in which a grouped OX Drive Stand‐Alone setup is operated. Multiple users’ file occupation gets accounted to a master user account.

Furthermore Open‐Xchange allows changing the running setups at any time to adjust the file storage usages/associations according to possibly changing needs/requirements.

=== Note ===

Please note that with introducing the concept of having user-associated file storages, the output for "listfilestore" command-line tool changed. Since also a user can be accounted to a file storage's capacity, the output changed to be:

/opt/open-xchange/sbin/listfilestore -A oxadminmaster -P secret
id path size reserved used max-entities cur-entities
2 file:///var/opt/filestore 1000 300 0 5000 2

Hence, "maxctx" is replaced with "max-entities" and "curctx" is replaced with "cur-entities"

== Seamless integration and flexibility ==
The new more flexible approach fits seamlessly into existing context/file storage setups. Thus there is no need to change anything, unless demanded by administrator

=== The fall‐back setup ===

[[Image:file_storage_picture4.png|The fall-back setup|650px]]

Everything stays as is. There is a storage‐per‐context association and every file is held in that storage. There are no user‐specific file storage attributes set in user table.

=== Slow mass storage vs. fast file storage setup ===

[[Image:file_storage_picture5.png|Slow mass storage|650px]]

There are two storages available: a file‐based and an S3 storage (assuming that the S3 one would be faster). While the context has the file‐based storage set, users in that context do have individual name spaces in the S3 storage.

That way common files (PIM/Signature attachments, thumbnails) are stored to context‐ associated file‐based storage while Drive documents are stored in the individual user name spaces in the S3 storage. Every user is allowed to occupy up to 10GB of space in the S3 storage (this can be varied as well).

=== OX Drive Stand‐Alone – Single User ===

[[Image:file_storage_picture6.png|OX Drive Stand-Alone - Single User|650px]]

Again there two file storages. Again the file‐based one is assumed to serve the slow mass storage behavior while S3 is assumed to be the fast storage.

Context designated to the Single User scenario for OX Drive Stand‐Alone operation, do hold only one user that has its individual name space associated in the S3 storage.

Again common files (PIM/Signature attachments, thumbnails) are stored in the context‐ associated file‐based storage while Drive documents are stored in the individual user name spaces in the S3 storage of each context. Every Drive document accounts the user‐sensitive quota of the associated user.

=== OX Drive Stand‐Alone – Business Account ===

[[Image:file_storage_picture7.png|OX Drive Stand-Alone - Business Account|650px]]

There two different file storages as in the previous setups. Again the file‐based one is assumed to serve the slow mass storage behavior while S3 is assumed to be the fast storage.

For this setup users do not hold their own individual name space in the S3 storage, but all share the same name space of the master user in the S3 storage. Moreover there are no dedicated user quotas, but all Drive documents do account to the master user’s quota

== Extensions to provisioning command‐line tools ==

=== createuser ===

The existing createuser CLI is enhanced by the following options
‐q/‐‐quota The file storage quota in MB for associated user
‐f/‐‐filestore The identifier for the file storage.
‐o/‐‐owner The owner for the file storage. If no owner is given and f/filestore option is set, the user itself is taken as owner

=== changeuser ===

The existing changeuser CLI is enhanced by the following option
‐q/‐‐quota The file storage quota in MB for associated user

'''Note:''' Option ALLOW_CHANGING_QUOTA_IF_NO_FILESTORE_SET in file 'AdminUser.properties' controls if a user file storage is automatically enabled if the ‐q/‐‐quota option is given on a 'changeuser' invocation as an alternative to 'movecontextfilestore2user'. For users without a user file storage the 'changeuser' CLT needs to be called with a quota value different to unlimited (-1) and unlimited quota will only be enabled in case the user already has a user file storage.

=== movecontextfilestore2user ===

Move a user’s files from a context to an individual storage name space. 
Usage: movecontextfilestore2user

‐h,‐‐help Prints a help text
‐‐environment Show info about commandline environment
‐‐nonl Remove all newlines (\n) from output
‐i,‐‐userid <userid> | Id of the user
‐u,‐‐username <username> | Username of the user
‐A,‐‐adminuser <adminuser> ? Admin username
‐P,‐‐adminpass <adminpass> ? Admin password
‐c,‐‐contextid <contextid> | The id of the context
‐N,‐‐contextname <contextname> | context name
‐f,‐‐filestore <filestore> * The identifier for the file storage.
‐q,‐‐quota <quota> * The file storage quota in MB for associated user.

Entries marked with an asterisk (*) are mandatory.
Entries marked with an question mark (?) are mandatory depending on your configuration.
Entries marked with a pipe (|) are mandatory for one another which means that at least one of them must be set.

=== moveuserfilestore2context ===

The counterpart for the previous CLI. Move a user's files from his individual storage name space to the context storage name space. 
Usage: moveuserfilestore2context

‐h,‐‐help Prints a help text
‐‐environment Show info about commandline environment
‐‐nonl Remove all newlines (\n) from output
‐i,‐‐userid <userid> | Id of the user
‐u,‐‐username <username> | Username of the user
‐A,‐‐adminuser <adminuser> ? Admin username
‐P,‐‐adminpass <adminpass> ? Admin password
‐c,‐‐contextid <contextid> | The id of the context
‐N,‐‐contextname <contextname> | context name

Entries marked with an asterisk (*) are mandatory.
Entries marked with an question mark (?) are mandatory depending on your configuration.
Entries marked with a pipe (|) are mandatory for one another that means that at least one of them must be set.

=== moveuserfilestore2master ===
Move a user's files from his individual storage name space to the storage name space of specified master. 
Usage: moveuserfilestore2master

‐h,‐‐help Prints a help text
‐‐environment Show info about commandline environment
‐‐nonl Remove all newlines (\n) from output
‐i,‐‐userid <userid> | Id of the user
‐u,‐‐username <username> | Username of the user
‐A,‐‐adminuser <adminuser> ? Admin username
‐P,‐‐adminpass <adminpass> ? Admin password
‐c,‐‐contextid <contextid> | The id of the context
‐N,‐‐contextname <contextname> | context name
‐m,‐‐master <master> Master user id. If not set, the context administrator is assumed to be the master user.

Entries marked with an asterisk (*) are mandatory.
Entries marked with an question mark (?) are mandatory depending on your configuration.
Entries marked with a pipe (|) are mandatory for one another, which means that at least one of them, must be set.

=== movemasterfilestore2user ===
Move a user's files from a master account name space to an individual storage name space. 
Usage: movemasterfilestore2user

‐h,‐‐help Prints a help text
‐‐environment Show info about commandline environment
‐‐nonl Remove all newlines (\n) from output
‐i,‐‐userid <userid> | Id of the user
‐u,‐‐username <username> | Username of the user
‐A,‐‐adminuser <adminuser> ? Admin username
‐P,‐‐adminpass <adminpass> ? Admin password
‐c,‐‐contextid <contextid> | The id of the context
‐N,‐‐contextname <contextname> | context name
‐m,‐‐master <master> Master user id. If not set, the context administrator is assumed to be the master user.
‐f,‐‐filestore <filestore> * The identifier for the file storage.
‐q,‐‐quota <quota> * The file storage quota in MB for associated user.

Entries marked with an asterisk (*) are mandatory.
Entries marked with an question mark (?) are mandatory depending on your configuration.
Entries marked with a pipe (|) are mandatory for one another, which means that at least one of them, must be set.

== Useful command‐line tools ==

The following command‐line tools might be useful to get an overview

* listfilestore to list available file storages that can be assigned to contexts/users
* listcontext to get the quota limit specified per context or -1 if none
* listuser to get the quota limit specified per user or -1 if none
* listuserfilestores to get a listing of users that use their own user file storage

2016-11-03T07:18:44Z

Thorben: /* Parameters */

== createcontext ==

'''<code>createcontext</code>''' is the tool to create new contexts. A context is an independent instance within the createcontext Open-Xchange system and holds users, groups
and resources and all their objects. Data from one context is not visible to other contexts. Module access (calendar, tasks, email) can be set via predefined "access combination names". These
names can be configured on the server side. All users which are created during later use of the "createuser" tool will inherit the module access rights from the context. If you do not specify any
access rights on createcontext minimal access rights will be granted. Currently, these are Webmail and Contacts access rights.

=== Parameters ===

{| border="1"
|-
| -h,--help
|Prints a help text
|-
| --environment
|Show info about commandline environment
|-
| --nonl
|Remove all newlines (\n) from output
|-
| --responsetimeout <integer>
|response timeout in seconds for reading response from the backend (default 0s; infinite) '''Available with v7.8.0'''
|-
| -c,--contextid <integer>
|The id of the context, when starting with 0, 0 is deleted
|-
| -q,--quota <integer>
|Context wide filestore quota in MB. -1 = unlimited. Note: The context-associated filestore is not only used by Infostore/Drive module, but also for other features like snippets/signatures, thumbnail cache, PIM attachments, etc. Thus even if you don't use the Infostore/Drive, you should always set an appropriate amount so users can store signatures.
|-
| -u,--username <string>
|Username for the new context admin user
|-
| -d,--displayname <string>
|Displayname for the new context admin user
|-
| -g,--givenname <string>
|Given name for the new context admin user
|-
| -s,--surname <string>
|Surname/last name for the new context Admin user
|-
| -p,--password <string>
|Password for the new context Admin user
|-
| -e,--email <string>
|Primary E-Mail address for the new context Admin user
|-
| -l,--lang <lang>
|Language for the new context Admin user
|-
| -t,--timezone <timezone>
|Timezone for the new context Amin user
|-
| -N,--contextname <string>
|Context name
|-
| -L,--addmapping <string>
|Add login mappings separated by ","
|-
| -F,--destination-store-id <integer>
|Specifies the optional file store identifier to which the context gets assigned; if missing the file store gets auto-detected
|-
| -D,--destination-database-id <integer>
|Specifies the optional database identifier to which the context gets assigned; if missing the database gets auto-detected
|-
| --access-combination-name <access-combination-name>
|Access combination name
|-
| --access-denied-portal <on/off>
|Denies portal access (Default is off)
|-
| --csv-import <CSV file>
| Full path to CSV file with user data to import. This option makes mandatory options obsolete, except credential options (if needed).
|}

==== --csv-import <CSV file> ====

Full path to CSV file with user data to import. This option makes mandatory command line options obsolete, except credential options (if needed). But they
have to be set in the CSV file.

With this option you can specify a csv file (a full pathname must be given) with the data which should be imported. The columnnames in the CSV file must be
the same as the long-options of the command line tools, without the prefix "--".

This option will normally be used to fill new large installations with the new data. So instead of calling
the command line tools in a shell script every time, just a csv file needs to be created, containing the whole data.

Note that the credentials of the masteradmin in the createcontext call
must be given on the command line with the -A and -P options nevertheless - if authentication is enabled. If the createuser command line tool is used, the credentials are part of the csv file, and
cannot be set as options on the command line itself. The reason for this different behavior is that different contexts have different credentials for the admin user, so they must be set in every
line of the csv file. Opposed to this the credentials of the masteradmin are always the same.

==== Extra parameters when authentication is enabled ====

{| border="1"
|-
| -A,--adminuser <string>
|Master Admin user name
|-
| -P,--adminpass <string>
|Master Admin password
|}

=== Return value ===

<code>0</code> on success

<code>>0</code> on failure

=== Mandatory parameters ===

'''<code>contextid {adminuser adminpass} quota username displayname givenname surname password email</code>'''

=== Command output ===

On success:

<code>context <contextid> created</code>

On
failure:

<code>context <contextid> could not be created: <reason from server></code>

=== Example ===

<code>root@oxhe~# </code>'''<code>/opt/open-xchange/sbin/createcontext
-c 123 -q 1000 -N CompanyA -u "admin" -d "Admin of CompanyA" -g John -s Example -p newpw -e john@example.com</code>'''

<code>context 123
created</code>

== deletecontext ==

'''<code>deletecontext</code>''' is the tool to delete contexts and all data stored that belong to it. This includes all database entries and files in the infostore but no
E-Mail components.

=== Parameters ===

{| border="1"
|-
| -h,--help
|Prints a help text
|-
| --environment
|Show info about commandline environment
|-
| --nonl
|Remove all newlines (\n) from output
|-
| --responsetimeout <integer>
|response timeout in seconds for reading response from the backend (default 0s; infinite) '''Available with v7.8.0'''
|-
| -c,--contextid <contextid>
|The id of the context
|-
| -N,--contextname <contextname>
|Context name
|}

=== Extra parameters when authentication is enabled ===

{| border="1"
|-
| -A,--adminuser <string>
|Master Admin user name
|-
| -P,--adminpass <string>
|Master Admin password
|}

=== Return value ===

<code>0</code> on success

<code>>0</code> on failure

=== Mandatory parameters ===

'''<code>(contextid or contexname) {adminuser adminpass}</code>'''

=== Command output ===

On success:

<code>context <contextid> deleted</code>

On failure:

<code>context
<contextid> could not be deleted: <reason from server></code>

=== Example ===

<code>root@oxhe~# </code>'''<code>/opt/open-xchange/sbin/deletecontext -c
123</code>'''

<code>context 123 deleted</code>

== listcontext ==

'''<code>listcontext</code>''' is the tool to list and search for contexts.

=== Parameters ===

{| border="1"
|-
| -h,--help
|Prints a help text
|-
| --environment
|Show info about commandline environment
|-
| --nonl
|Remove all newlines (\n) from output
|-
| --responsetimeout <integer>
|response timeout in seconds for reading response from the backend (default 0s; infinite) '''Available with v7.8.0'''
|-
| -s,--searchpattern <string>
|Search/List pattern, default “*”
|-
| --csv
|Command output as csv
|}

=== Extra parameters when authentication is enabled ===

{| border="1"
|-
| -A,--adminuser <adminuser>
|Master Admin user name
|-
| -P,--adminpass <string>
|Master Admin password
|}

=== Return value ===

<code>0</code> on success

<code>>0</code> on failure

=== Mandatory parameters ===

'''<code>{adminuser adminpass}</code>'''

=== Command output ===

Standard output:

<pre>cid fid fname enabled qmax qused name
lmappings . . ... ... ... ... ... ...
</pre>

csv output:

<code>id,filestore_id,filestore_name,enabled,max_quota,used_quota,name,lmappings</code>

=== Example ===

<pre>root@oxhe:/opt/open-xchange/sbin# ./listcontexts cid fid fname
enabled qmax qused name lmappings 6 3 6_ctx_store true 1000 0 customerA 6,customerA,secondlogin
</pre>

== disablecontext ==

'''<code>disablecontext</code>''' is the tool to disable contexts. Whenever a customer tries to log in to a disabled context, the login is denied.

=== Parameters ===

{| border="1"
|-
| -h,--help
|Prints a help text
|-
| --environment
|Show info about commandline environment
|-
| --nonl
|Remove all newlines (\n) from output
|-
| --responsetimeout <integer>
|response timeout in seconds for reading response from the backend (default 0s; infinite) '''Available with v7.8.0'''
|-
| -c,--contextid <integer>
|The id of the context
|-
| -N,--contextname <string>
|Context name
|}

=== Extra parameters when authentication is enabled ===

{| border="1"
|-
| -A,--adminuser <string>
|Master Admin user name
|-
| -P,--adminpass <string>
|Master Admin password
|}

=== Return value ===

<code>0</code> on success

<code>>0</code> on
failure

=== Mandatory parameters ===

'''<code>(contextid or
contextname) {adminuser adminpass}</code>'''

=== Command output ===

On
success:

<code>context <contextid> disabled</code>

On failure:

<code>context <contextid> could not be disabled:
<reason from server></code>

=== Example ===

<code>root@oxhe~# </code>'''<code>/opt/open-xchange/sbin/disablecontext -c 123</code>'''

<code>context 123
disabled</code>

== disableallcontexts ==

'''<code>disableallcontexts</code>''' is the tool to disable all contexts. Whenever a customer tries to log in to a disabled context, the login is denied.

=== Parameters ===

{| border="1"
|-
| -h,--help
|Prints a help text
|-
| --environment
|Show info about commandline environment
|-
| --nonl
|Remove all newlines (\n) from output
|-
| --responsetimeout <integer>
|response timeout in seconds for reading response from the backend (default 0s; infinite) '''Available with v7.8.0'''
|}

=== Extra parameters when authentication is enabled ===

{| border="1"
|-
| -A,--adminuser <string>
|Master Admin user
name
|-
| -P,--adminpass <string>
|Master Admin password
|}

=== Return value ===

<code>0</code> on success

<code>>0</code> on
failure

=== Mandatory parameters ===

'''<code>{adminuser
adminpass}</code>'''

=== Command output ===

On success:

<code>all contexts disabled</code>

On failure:

<code>all contexts could not be disabled: <reason from server></code>

=== Example ===

<code>root@oxhe~# </code>'''<code>/opt/open-xchange/sbin/disableallcontexts</code>'''

<code>all contexts disabled</code>

== enablecontext ==

'''<code>enablecontext</code>''' is the tool to enable a disabled context.

=== Parameters ===

{| border="1"
|-
| -h,--help
|Prints a help text
|-
| --environment
|Show info about commandline environment
|-
| --nonl
|Remove all newlines (\n) from
output
|-
| -c,--contextid <integer>
|The id of the context
|-
| -N,--contextname <string>
|Context name
|}

=== Extra parameters when authentication is enabled ===

{| border="1"
|-
| -A,--adminuser <adminuser>
|Master Admin user name
|-
| -P,--adminpass <string>
|Master Admin password
|}

=== Return value ===

<code>0</code> on success

<code>>0</code> on failure

=== Mandatory parameters ===

'''<code>(contextid or contextname) {adminuser adminpass}</code>'''

=== Command output ===

On success:

<code>context <contextid> enabled</code>

On failure:

<code>context <contextid> could not be enabled: <reason from server></code>

=== Example ===

<code>root@oxhe~#
</code>'''<code>/opt/open-xchange/sbin/enablecontext -c 123</code>'''

<code>context <contextid> enabled</code>

== enableallcontexts ==

'''<code>enableallcontexts</code>''' is the tool to enable all disabled contexts.

=== Parameters ===

{| border="1"
|-
| -h,--help
|Prints a help text
|-
| --environment
|Show info about commandline environment
|-
| --nonl
|Remove all newlines (\n) from
output
|}

=== Extra parameters when authentication is enabled ===

{| border="1"
|-
| -A,--adminuser <string>
|Master Admin user name
|-
| -P,--adminpass
<string>
|Master Admin password
|}

=== Return value ===

<code>0</code> on success

<code>>0</code> on failure

=== Mandatory parameters ===

'''<code>{adminuser adminpass}</code>'''

=== Command output ===

On success:

<code>all contexts enabled</code>

On
failure:

<code>all contexts could not be enabled: <reason from server></code>

=== Example ===

<code>root@oxhe~# </code>'''<code>/opt/open-xchange/sbin/enableallcontexts</code>'''

<code>all contexts enabled</code>

== getcontextcapabilities ==

'''<code>getcontextcapabilities</code>''' is the tool to list available capabilities for a certain context.

=== Parameters ===

{| border="1"
|-
| -h,--help
|Prints a help text
|-
| --environment
|Show info about commandline environment
|-
| --nonl
|Remove all newlines (\n) from output
|-
| --responsetimeout <integer>
|response timeout in seconds for reading response from the backend (default 0s; infinite) '''Available with v7.8.0'''
|-
| -c,--contextid <integer>
|The id of the context
|-
| -N,--contextname <contextname>
|context name
|}

=== Extra parameters when authentication is enabled ===

{| border="1"
|-
| -A,--adminuser <string>
|Context Admin user name
|-
| -P,--adminpass <string>
|Context Admin password
|}

=== Return value ===

<code>0</code> on success

<code>>0</code> on failure

=== Mandatory parameters ===
<code>contextid adminuser adminpass</code>

=== Command output ===

Either "There are no capabilities set for context <context-id>"
or a line-wise listing of identifiers for available capabilities

=== Example ===

<pre> root@oxhe:~# /opt/open-xchange/sbin/getcontextcapabilities -c 6
</pre>

== changecontext ==

'''<code>changecontext</code>''' makes context-wide changes. 

If you specify module access options; e.g. "--access-edit-password on"; then please be aware that basic module access set is the one from context's administrator. Meaning any option not explicitly specified as CLI argument will fall-back to context administrator setting for _every_ user in associated context. 

You can use changecontext to change the current quota for a given context. When the context has more changecontext space in use than the new quota allows,
the customer is only able to delete files until the usage is below quota. Module access (calendar,tasks,email) can be set via predefined "access combination names". These names can be configured on
the server side. All users which are created during later use of the "createuser" tool will inherit the module access rights from the context. If you do not specify any access rights on
createcontext minimal access rights will be granted. Currently, these are Webmail and Contacts access rights.

There are some default combinations in the ModuleAccessDefinitions.properties
file on the admin server, like:

{| border="1"
|-
|webmail=webmail, contacts, globaladdressbookdisabled, collectemailaddresses, editpassword
|-
|pim=webmail, ''calendar'', contacts, ''tasks'', globaladdressbookdisabled, collectemailaddresses, ''multiplemailaccounts'', ''subscription'', ''publication'', editpassword
|-
|pim_infostore=webmail, calendar, contacts, tasks, ''infostore'', ''webdav'', globaladdressbookdisabled, collectemailaddresses, multiplemailaccounts, subscription, publication
|-
|pim_mobility=webmail, calendar, contacts, tasks, syncml, ''usm'', activesync, globaladdressbookdisabled, collectemailaddresses, multiplemailaccounts, subscription, publication, ''editpassword''
|-
|groupware_standard=webmail, calendar, contacts, infostore, tasks, webdav, ical, vcard, readcreatesharedfolders, delegatetask, editpublicfolders, editgroup, editresource, editpassword, collectemailaddresses, multiplemailaccounts, subscription, publication (Groupware Standard always gets new features except mobility and OXtender. )
|-
|groupware_premium=webmail, calendar, contacts, infostore, tasks, webdav, ''webdavxml'', ical, vcard, ''syncml, ''usm'', ''olox20'', ''activesync'', readcreatesharedfolders, delegatetask, editpublicfolders, editgroup, editresource, editpassword, collectemailaddresses, multiplemailaccounts, subscription, publication
|-
|all=webmail, calendar, contacts, infostore, tasks, webdav, webdavxml, ical, vcard, syncml, usm, olox20, activesync, readcreatesharedfolders, delegatetask, editpublicfolders, editgroup, editresource, editpassword, ''publicfoldereditable'', collectemailaddresses, multiplemailaccounts, subscription, publication (This is a right tailored to a context administrator)
|}

'''Note:''' Italics denote additional rights in comparison to the previous set where applicable.

When having changed the access rights of the context and its users with "changecontext" the "downgrade" command should be called on the admin server. All unnecessary data are removed from
the data base via "groupware api". If e. g. the context 1 is changed from "pim_infostore" to "webmail", the "downgrade" command has to be called for this context then. Then, all unnecessary
folders for this context are removed from the data base.

=== Parameters ===

{| border="1"
|-
| -h,- -help
|Prints a help text
|-
| --environment
|Show info about commandline environment
|-
| --nonl
|Remove all newlines (\n) from output
|-
| --responsetimeout <integer>
|response timeout in seconds for reading response from the backend (default 0s; infinite) '''Available with v7.8.0'''
|-
| -c,- -contextid <integer>
|The id of the context
|-
| -N,- -contextname <string>
|The name of the context
|-
| -L,- -addmapping <string(s)>
|Add login mappings. Separated by ","
|-
| -R,- -removemapping <stirng(s)>
|Remove login mappings. Separated by ","
|-
| -q,- -quota <integer>
|Quota for the context filestore in MB
|-
| --access-combination-name <access-combination-name>
|Access combination name
|-
| --capabilities-to-add <capabilities-to-add>
| The capabilities to add as a comma-separated string (from 7.2.0 on)
|-
| --capabilities-to-remove <capabilities-to-remove>
| The capabilities to remove as a comma-separated string (from 7.2.0 on)
|-
| --capabilities-to-drop <capabilities-to-drop>
|The capabilities to drop; e.g. cleanse from storage; as a comma-separated string (from 7.6.0 on)
|-
| --quota-module <quota-module>
|The identifier of the module to which to apply the quota value (from 7.2.0 on)
|-
| --quota-value <quota-value>
| from v7.2.0 on: The quota value; zero is unlimited from v7.6.0 on: The numeric quota value specifying the max. number of items allowed for context. Zero is unlimited. A value less than zero deletes the quota entry (and falls back to configured behavior)
|}

=== Extra parameters when authentication is enabled ===

{| border="1"
|-
| -A,- -adminuser <string>
|Master Admin user name
|-
| -P,- -adminpass <string>
|Master Admin password
|}

=== Return value ===

<code>0</code> on success

<code>>0</code> on
failure

=== Mandatory parameters ===

'''<code>(contextid or
contextname) {adminuser adminpass} and at minimum one attribute to change</code>'''

=== Command output ===

On success:

<code>context <contextid> changed</code>

On failure:

<code>context
<contextid> could not be changed: <reason from server></code>

=== Example ===

<code>root@oxhe~# </code>'''<code>/opt/open-xchange/sbin/changecontext -c 123 -q
500</code>'''

<code>context 123 changed</code>

== getAdminId ==

Returns the ID of the context administrator.

[[Category: Administrator]]

[[Category: AppSuite]]
[[Category: AdminGuide]]
[[Category: CommandLineTools]]

2016-03-01T10:01:30Z

Thorben: /* Configuration */

= Common preparations =
This page shows how to setup external file stores. For all of these file stores you have to install the package "open-xchange-oauth", which provides the necessary authentication mechanisms.

Moreover your setup is required to be reachable via HTTPS, since the providers expect that a call-back URL to your setup is specified. Such a call-back URL is only accepted if it contains the <source enclose="none" lang="java">"https://"</source> scheme., e.g.:
<syntaxhighlight lang="java">
"https://my.oxsetup.invalid/ajax/defer"
</syntaxhighlight>

== Keep HTTPS protocol ==
[[Appsuite:Grizzly#Cluster_setup]] shows that HTTPS communication is terminated by the Apache balancer in front of the Open-Xchange nodes. To let the Open-Xchange application know about the HTTPS protocol that is used to communicate with the Apache server:
* Either set a special header in the SSL virtual hosts configurations in Apache to forward this information. The de facto standard for this is the <source enclose="none" lang="java">"X-Forwarded-Proto"</source> header. See [[Appsuite:Grizzly#X-FORWARDED-PROTO_Header]] for how to setup that header.
* Or force the Open-Xchange application to assume it is reached via SSL through setting property <source enclose="none" lang="properties">"com.openexchange.forceHTTPS=true"</source> in file ''/opt/open-xchange/etc/server.properties''.

== Deferrer URL ==
Open-Xchange application uses the deferrer URL as call-back for some of the providers, which use OAuth v2.0 authentication (such as Google).

If your OX server is reachable only via one host name, you won't have to do anything. If it is reachable by more than one host name, create or open the file ''/opt/openexchange/etc/groupware/deferrer.properties'' and set the properties therein as such:
<syntaxhighlight lang="properties">
com.openexchange.http.deferrer.url=https://mymaindomain.invalid
</syntaxhighlight>

= Dropbox =

To setup the Dropbox file store you have to install the package "open-xchange-file-storage-dropbox".

== Registering your app ==
* Log in to your Dropbox account [https://www.dropbox.com/login here], and create your Dropbox app [https://www.dropbox.com/developers/apps/create here]
* There are two options available creating an app, Drops-in App & Dropbox API App. Please select '''Dropbox API''' app and enter the name of your app.
* Go to [http://%20https//www.dropbox.com/developers/apps App Console] and select your created app. Select settings tab to view the <source enclose="none" lang="java">APP_KEY</source> (App key) and <source enclose="none" lang="java">SECRET_KEY</source> (App secret)

== Configuration ==
In addition you have to configure the following properties in file ''/opt/open-xchange/etc/dropboxoauth.properties'':

* Enable the OAuth connector to Dropbox OAuth
<syntaxhighlight lang="properties">
com.openexchange.oauth.dropbox=true
</syntaxhighlight>
 

* Set the API key and secret
<syntaxhighlight lang="properties">
com.openexchange.oauth.dropbox.apiKey=REPLACE_THIS_WITH_DROPBOX_APP_KEY
com.openexchange.oauth.dropbox.apiSecret=REPLACE_THIS_WITH_DROPBOX_APP_SECRET
</syntaxhighlight>
 

You can define them system-wide or via the config cascade mechanism.

{{InstallPlugin|pluginname=open-xchange-file-storage-dropbox|toplevel=products|sopath=appsuite/stable/backend|version=App Suite}}

= Google Drive =

To setup the Google Drive file store you have to install the package "open-xchange-file-storage-googledrive".

== Registering your app ==
* Log in to your Dropbox account [https://www.dropbox.com/login here], and create your Dropbox app [https://www.dropbox.com/developers/apps/create here]
* There are two options available creating an app, Drops-in App & Dropbox API App. Please select '''Dropbox API''' app and enter the name of your app.
* Go to [http://%20https//www.dropbox.com/developers/apps App Console] and select your created app. Select settings tab to view the <source enclose="none" lang="java">APP_KEY</source> (App key) and <source enclose="none" lang="java">SECRET_KEY</source> (App secret)

== Configuration ==
In addition you have to configure the following properties in file ''/opt/open-xchange/etc/googleoauth.properties'':

* Enable the OAuth connector to Google OAuth
<syntaxhighlight lang="properties">
com.openexchange.oauth.google=true
</syntaxhighlight>
 

* Set the API key and secret
<syntaxhighlight lang="properties">
com.openexchange.oauth.google.apiKey=REPLACE_THIS_WITH_YOUR_CLIENT_ID
com.openexchange.oauth.google.apiSecret=REPLACE_THIS_WITH_YOUR_CLIENT_SECRET
</syntaxhighlight>
 

* Set the redirect URL. Please ensure the following conditions are met:
** The redirect URL specified in the Google App needs to be the same as the one specified by this property.
** The redirect URI uses "https://" as protocol
** The redirect URI follows the pattern: "https://" + <host-name> + "/ajax/defer"
<syntaxhighlight lang="properties">
com.openexchange.oauth.google.redirectUrl=
</syntaxhighlight>
E.g. <source enclose="none" lang="java">"https://myappsuite.mydomain.invalid/ajax/defer"</source>
 

* Set the product ID of the registered Google app
<syntaxhighlight lang="properties">
com.openexchange.oauth.google.productName=
</syntaxhighlight>
 

You can define them system-wide or via the config cascade mechanism.

{{InstallPlugin|pluginname=open-xchange-file-storage-googledrive|toplevel=products|sopath=appsuite/stable/backend|version=App Suite}}

= Microsoft Onedrive =
To setup the Microsoft OneDrive file store you have to install the package "open-xchange-file-storage-onedrive". In addition you have to configure the following properties:
<pre># Enable/disable
com.openexchange.oauth.msliveconnect=true
# The API key
com.openexchange.oauth.msliveconnect.apiKey=REPLACE_THIS_WITH_YOUR_MS_LIVE_CONNECT_KEY
# The API secret
com.openexchange.oauth.msliveconnect.apiSecret=REPLACE_THIS_WITH_YOUR_MS_LIVE_CONNECT_SECRET
# The redirect URL
# e.g. "https://myappsuite.mydomain.invalid/ajax/defer"
com.openexchange.oauth.msliveconnect.redirectUrl=REPLACE_THIS_WITH_YOUR_MS_LIVE_CONNECT_REDIRECT_URL
</pre>

You can define them system wide within msliveconntectoauth.properties or via the config cascade mechanism.

{{InstallPlugin|pluginname=open-xchange-file-storage-onedrive|toplevel=products|sopath=appsuite/stable/backend|version=App Suite}}

= Boxcom =
To setup the Boxcom file store you have to install the package "open-xchange-file-storage-boxcom". In addition you have to configure the following properties:

<pre># Enable/disable
com.openexchange.oauth.boxcom=true
# The API key
com.openexchange.oauth.boxcom.apiKey=REPLACE_THIS_WITH_YOUR_BOX_COM_KEY
# The API secret
com.openexchange.oauth.boxcom.apiSecret=REPLACE_THIS_WITH_YOUR_BOX_COM_SECRET
# The redirect URL
# e.g. "https://myappsuite.mydomain.invalid/ajax/defer"
com.openexchange.oauth.boxcom.redirectUrl=REPLACE_THIS_WITH_YOUR_BOX_COM_REDIRECT_URL
</pre>
You can define them system wide within boxcomoauth.properties or via the config cascade mechanism.

{{InstallPlugin|pluginname=open-xchange-file-storage-boxcom|toplevel=products|sopath=appsuite/stable/backend|version=App Suite}}