Oc5 Enterprise Appliance Tour

8/11/2019 Oc5 Enterprise Appliance Tour

1/13

ownCloud 5.0 Enterprise Edition

RC Appliance Tour

ownCloud, Inc.

10 Foster Road

Lexington, MA 02421United States

mail: [email protected]

phone: +1 (877) 394-2030

https://www.owncloud.com


2/13

YOUR CLOUD, YOUR DATA,YOUR WAY!

ownCloud 5 Enterprise Edition RC Appliance Tour

Welcome to ownCloud 5 Enterprise Edi-

tion! We hope you enjoy your quick tour

of the most secure, on site enterprise file

sync and share solution available. Only

with ownCloud can you install the server

on site, or wherever you choose, integra-

te with your existing infrastructure, and

extend the functionality to meet your

file needs today and into the future all

while still providing the simple consu-mer file sync and share experience your

end users demand.

Read on to learn more about how to

make use of our new ownCloud 5 Enter-

prise Edition Release Candidate virtual

appliance, and to see for yourself what

ownCloud can do for you. If you have any

problems or questions with your appli-

ance, please email [email protected]

and we will get back to you.

Getting Started

Before you begin, you will need a virtua-

lized environment to import and run our

OVF virtual appliance. While ownCloud

can run in extremely small instances, we

built the appliance to use 2GB of RAM

and 48 GB of disk space. We recommend

at least a full CPU for the appliance.

While additional memory and an additi-

onal CPU will improve performance, disk

size will bound the total file uploads to

ownCloud, so it is always a good idea to

add more disk if you can.

The virtual appliance is designed to

run on most hypervisors, and includes

ownCloud 5 Enterprise Edition installed

on top of MySQL, Apache2, and MySQL.

For network access, make sure that the

VM is set to bridge the local network,

or you will not be able to sync with the

server. To make life simpler for you, we

configured the appliance to expect a

DHCP address so be sure you provide

one on the network where the appliance

is attached.

We also encourage you to take a look at

four specific ownCloud plug-in appli-

cations supplied with this appliance:

LDAP/AD integration, Audit Log and

Share Logging, and the Provisioning API.All four of these apps provide just a glim-

pse of how ownCloud can be integrated

into your existing environment, and the

power of a fully on-site solution integra-

ted into your data center. More informa-

tion can be found below on these issues

specifically.

Be sure to bring your iOS or Android

devices too, as the mobile apps can be

downloaded from the Apple App Store

or Google Play store respectively. To

connect your desktop device, download

the appropriate Windows, Mac or Linux

clients from ownCloud.com.

1) Get the Appliance

Chances are you already found the ap-

pliance, but if not, it can be downloaded

from www.owncloud.com/download . Be

sure to grab the ownCloud 5 Enterprise

Edition!

2) Boot the Appliance

Once you have downloaded the file,

import it into your virtualization tool and

boot it. The credentials are:

User: root

Password: linux

Once you are at the command line,

immediately change the root password

using the following command:

passwd root1

Now that this is out of the way, it is

important to get the URL to the server

for the next step. The IP address of

the server will be displayed when the

server completes booting. If there is no

IP address, check your virtual machine

settings, and reboot the virtual machine

by typing reboot at the command line.

Be sure to note the IP address, you willneed it for the next step.

Note: a software firewall has been ins-

talled and activated on this appliance,

and it allows port 22 SSH, and port 80

and 443 for HTTP(s). You can use this

IP address for SSH connections if you

choose.

3) Configure ownCloud

Open a browser and point it to the

IP address above with the following

address:

x.x.x.x\owncloud

You should be prompted with the ownC-

loud setup wizard. In this page you will

see three things:

1) Admin Username

2) Admin Password

3) Advanced

Enter a username that you desire for

the ownCloud administrator, enter a

password, and then clicked advanced

settings. In this first part, you will leave

the default:

Data directory:

/srv/www/htdocs/owncloud/data

As you can see in the above configura-

tion, it is a simple matter to change the

data directory to use any other server

mounted storage. For this instance, we

1Security Notice: Please change the OS root password when you first log in! And, please note we have not installed an SSL certificate on this server, thus only

HTTP is accessible. As a result, we do not recommend using this instance in production, or with sensitive data over the Internet as currently configured.

Page 2


3/13


use the local attached storage inside theVM for simplicity.

On the same tab, you will also find a

button to choose MySQL. Click on the

MySQL tab to reveal the following fields,

and enter the associated information:

Database username: root

Database password: owncloud42

Database instance: oc5eerc2

Database location: localhost

As you can see here, it is a simple matter

to point this ownCloud instance to use

a database on a separate server. For

performance purposes we highly recom-

mend this as a setup in a production

environment, but for the purposes of a

test run through, a locally stored databa-

se will suffice.

In a production Enterprise Edition

appliance, two other database options

will show up in the database configura-

tion section: Microsoft SQL Server and

Oracle. In the ownCloud 5 Enterprise

Edition, both of these databases maybe used and configured in this page for

ownCloud use.

4) Welcome to ownCloud!

When a new user first logs into ownC-

loud, the First Run Wizard will pop up

on the screen. This can be configured

and customized for your environment,

but out of the box the existing pop-up

window outlines how to download the

ownCloud desktop client and mobileapps. Simply close the window. Now you

are looking at the primary ownCloud

user interface.

At this point, you may upload and

download files, create new folders, and

create and edit text files in the browser.

You may also rename files, restore old

versions of files (if any), share files with

other users or groups, delete files. If a

file is deleted, it can be restored through

the Deleted files button on the topright. This is the same basic file sync

and share interface any user will see in-

side ownCloud, and many have come to

expect from consumer grade solutions.

In addition, users will also have access

to the personal tab in the ownCloud

interface. To see your personal tab,

select the personal option in the top

right menu. Here you may set your email

address (used if you lose or forget your

password), change your password, add

a display name (such as your full name),

choose your language, see the WebDAV

URL for accessing ownCloud, and even

export this account to a zip file for back-

up. This is essentially the general user

interface.

Since you are logged in as the admi-

nistrator for ownCloud, you also have

three additional options in the top right

menu: Users, Apps and Admin. We will

now walk you through these menus and

unveil the true power of ownCloud.

Users

Click on the users tab, and you will see

a list of users on the system. When you

connect ownCloud to an Active Directory

(AD) or LDAP server, the list of users will

be displayed here. At this point, we have

not connected ownCloud to a directory,

so you should only see the admin ac-

count you set up on the initial install of

the system. Here you can add additional

accounts to the basic ownCloud usermanagement system. Simply type in the

username and password, and set an

existing or new group if you choose. You

can also set a default quota, and a spe-

cific quota. Only members of the group

admin are allowed to see this tab.

You may also set a group admin here, whe-

re a user of ownCloud can manage users

and user quota in the designated group.

Once you add a user, they too can log in to

ownCloud via the URL you are using.

Apps

The apps tab is the most powerful

component of ownCloud. In here you can

enable and disable all of the features of

ownCloud. Additional apps can easily be

created in PHP, installed, and enabled in

this interface. Simply select and app and

select Enable or Disable. In particular,

we invite you to try out a few existing

apps that help enterprises take advan-

tage of the on-site nature of ownCloud,

and integrate it in to the existing infra-

structure.

File Shared Access Logging App

Enables additional logging of shared

file and folder functions in the ownc-

loud.log file, providing a finer granu-

larity of recording. Simply enable the

app, and additional information will

start to appear in your owncloud.log

file, found in /srv/www/htdocs/ownc-

loud/data/owncloud.log .

LDAP User and Group Backend

Enable ownCloud to connect to one or

many Active Directory (AD) and LDAP

instances, including user names, dis-

play names, quota, group members

and more.

For more information on how to

configure Active Directory and LDAP

connections, see the appendix of this

document.

Log Audit Info Enables detailed

logging of user actions, such as

logins and logouts with IP addresses

and timestamps for more complete

activity logging. Simply enable the

app, and additional information will

start to appear in your owncloud.log

file, found in /srv/www/htdocs/ownc-

loud/data/owncloud.log .

Provisioning API Enables external

Page 3


4/13


automation systems to connect toownCloud and create users, set quota

and query total storage used.

For more information on how to access

and use the provisioning API, see the

appendix of this document.

Beyond those core apps, the following

apps are enabled in the ownCloud 5

Enterprise Edition Release Candidate:

Deleted files The ability for users to

see a list of files they deleted in the

web interface, and to restore those

deleted files back to their ownCloud

file directories.

First Run Wizard The window that

pops up for each user when they first

log in to the browser, displaying the

welcome message and the links to

the desktop client and mobile apps.

Image Viewer The app that makes

it possible to click on an image andsee a pop-up window displaying the

picture in the browser.

Share Files The ability for users to

share files with groups, other users of

ownCloud, and external parties using

links, as well as link passwords and

timed expiration.

Text Editor The ability for a user to

open a text file in the web browser,

edit it, and then save the changesback to the ownCloud server all

without downloading the file.

Versions The ability for a user to

see versions of their files with the

same name, and then revert to older

versions of their files through the web

browser.

In addition to these apps enabled by

default, there are several other apps that

are shipped with the ownCloud. Theseinclude:

ownCloud Dependencies Info Provi-

des a quick reference list for admins

to determine if they have installed all

of the required PHP modules required

for ownCloud to function properly

Anti-Virus App for Files Provides an

anti-virus plugin that scans all files

as they are uploaded to the server,

with the default action for infected

files configurable by the admin

Admin

The final tab in the ownCloud interface

is the Admin tab. In here you will find

the configuration options for all of the

enabled apps, as well as the built in low

viewer. Simply select the log level you

desire, and ownCloud will display the

most recent log files. And, of course, the

ownCloud.log file is itself available at

the path /srv/www/htdocs/owncloud/

data/owncloud.log

5) Mobile Apps

The ownCloud mobile apps provide a

simple, easy mechanism for Android and

iOS devices to connect to your ownCloud

server. Assuming you are on the same

network segment, or have configured

ownCloud for Internet access, simply

start the app and enter the URL:

x.x.x.x/owncloud

The app will connect to your ownCloud

instance and give you mobile access to

browse, download, preview, edit, and

upload files and much more. You can

find these apps at:

Apple iTunes: http://itunes.

apple.com/us/app/owncloud/

id543672169?ls=1&mt=8

Google Play:https://play.google.com/store/apps/details?id=com.owncloud.

android

6) Desktop Clients

The ownCloud desktop clients can be

installed on Windows, Linux and Mac

computers, and provide a small system

tray icon that keeps a folder in sync with

the server. Simply enter the URL of your

ownCloud server as you would with your

mobile client:

x.x.x.x/owncloud

The desktop client will then connect to

your server and keep the folder on your

desktop in sync with the folder on the

server. In addition to syncing the latest

files from your own account, files shared

with you will show up in the /ownCloud/

Shared folder on your desktop computer.

7) Have Fun

This appliance is provided in thisappliance to demonstrate some of the

new features of ownCloud 5 Enterprise

Edition. While we know ownCloud is the

only on site file sync and share solution

that can integrate with your existing

infrastructure, and be extended with

extensive plug-in applications capabi-

lities, dont just take our word for it. We

encourage you to give it a try, see what it

can do for you.

For more information on ownCloud, totalk to us about how to brand the entire

solution to match your companys look

and feel, for ownCloud technical details,

or any questions you may have, visit

ownCloud.com or contact us at

[email protected].

Page 4


5/13


Appendix 1:User Authentication

with LDAP

ownCloud ships an LDAP backend, which

allows full use of ownCloud for user log-

ging in with LDAP credentials including:

LDAP group support

File sharing with users and groups

Access via WebDAV and of course

ownCloud Desktop Client Versioning, external Storages and all

other ownCloud Goodies

To connect to an LDAP server the con-

figuration needs to be set up properly.

Once the LDAP backend is activated

(SettingsApps, choose LDAP user

and group backend, click on Enable)

the configuration can be found on

SettingsAdmin. Read on for a detailed

description of the configuration fields.

Basic Settings

The basic settings are all you need.

However, if you have a larger directory,

custom requirements or need to connect

to Active Directory (AD) you want to have

a look on the advanced settings after-

wards. The basic part allows you to set

up a working connection to your LDAP

server and use it with ownCloud.

Note that a hint will be shown on theright hand side, when hovering with the

mouse over an input field. This gives you

more context information while filling

out the settings.

Settings Details

Server configuration:

ownCloud can be configured to connect

to multiple LDAP servers. Using this

control you can pick a configuration

you want to edit or add a new one. The

button Delete Configuration deletes the

current configuration.

Example: 1. Serve

Host:

The host name of the LDAP server. It can

also be an ldaps:// URI, for instance.

Example: directory.my-company.com

Base DN:

The base DN of LDAP, from where all

users and groups can be reached. Sepa-rated Base DNs for users and groups can

be set in the Advanced tab. Neverthel-

ess, this field is mandatory.

Example: dc=my-company,dc=com

User DN:

The name as DN of a user who is able

to do searches in the LDAP directory.

Let it empty for anonymous access. It is

recommended to have a special system

user for ownCloud.

Example: uid=owncloudsystemuser,cn

=sysusers,dc=my-company,dc=com

Password:

The password for the user given above.

Empty for anonymous access.

User Login Filter:

The filter to use when a user tries to

login. Use %uid as placeholder for the

user name. Note, that login applies this

filter only, but not User List Filter. This

may change in future.

Example (allows login with

user name and email address):

(|(uid=%uid)(email=$uid))

User List Filter:

The filter to use when a search for users

will be executed.

Example: objectClass=posixAccount

Group Filter:

The filter to use when a search for

groups will be executed. In case you donot want to use LDAP groups in ownC-

loud, leave it empty.

Example: objectClass=posixGroup

Page 5


6/13


Advanced SettingsIn the LDAP Advanced settings section

you can define options that are less

common to set. They are not needed for

a working connection, unless you use a

non-standard Port, e.g. it can also have

a positive effect on the performance to

specify distinguished bases for user and

group searches.

The Advanced Settings are structured

into three parts: * Connection Settings *

Directory Settings * Special Attributes

Connection Settings

Configuration Active:

Enables or Disables the current configu-

ration. Disabled configuration will not

connect to the LDAP server.

Example: [X]

Port:

The port on which to connect to the LDAP

server.

Example: 389

Backup (Replica) Host:

A backup server can be defined here.

ownCloud tries to connect to the backup

server automatically when the main host

(as specified in basic settings) cannot

be reached. It is import that the backup

server is a replica of the main server,

because the object UUIDs must match.

Example: directory2.my-company.com

Backup (Replica) Port:

The port on which to connect to the

backup LDAP server. If no port is given,

but a host, then the main port (as speci-

fied above) will be used.

Example: 389

Disable Main Server:

You can manually override the main

server and make ownCloud only connect

to the backup server. It may be handy for

planned downtimes.

Example: [ ]

Use TLS:

Whether to use TLS encrypted connec-

tion to the LDAP server. This will be igno-

red when ldaps:// protocol is specified

in the host entries.

Example: [ ]

Case insensitive LDAP server (Windows):

Whether the LDAP server is running on a

Windows Host

Example: [ ]

Turn off SSL certificate validation:

Turns of check of valid SSL certificates.

Use it if needed for testing, only!

Example: [ ]

Cache Time-To-Live:

A cache is introduced to avoid unneces-

sary LDAP traffic, for example lookups

check whether the users exists on every

page request or WebDAV interaction. It is

also supposed to speed up the Admin

User page or list of users to share with,

once it is populated. Saving the confi-

guration empties the cache (changes

are not necessary). The time is given in

seconds.

Note that almost every PHP request

would require to build up a new connec-

tion to the LDAP server. If you require the

most up-to-date LDAP user connection,

it is recommended not to totally switch

off the cache, but define a minimum life

time of no less than 15s.

Example (10 min): 600

Page 6


7/13


Directory SettingsUser Display Name Field:

The attribute that should be used as

display name in ownCloud. Prior to

ownCloud 5 it was used as internal user

name. This is not the case anymore.

It also means that display names are

not permanent in ownCloud, i.e. if the

attributes value changes in LDAP, it

changes in ownCloud too. Display names

to not need to be unique, but you rather

want to specify a more or less unique

attribute here to avoid confusion.

Example: displayName

Base User Tree:


users can be reached. It needs to be

given completely despite to the Base DN

from the Basic settings. You can specifiy

multiple base trees, one in each line.

Example:

cn=programmers,dc=my-

company,dc=com

cn=designers,dc=my-company,dc=com

User Search Attributes:

These attributes are used when a search

for users with a search string is done.

This happens, for instance, in the share

dialogue. By default the user display

name attribute as specified above is

being used. Multiple attributes can be

given, one in each line.

Example:

displayName

mail

Group Display Name Field:

The attribute that should be used as

ownCloud group name. ownCloud

allows a limited set of characters (a-zA-

Z0-9.-_@), every other character will

be replaced in ownCloud. Once a group

name is assigned, it will not be changed,

i.e. changing this value will only have

effect to new LDAP groups.

Example: cn

Base Group Tree:


groups can be reached. It needs to be

given completely despite to the Base DN

from the Basic settings. You can specifiy

multiple base trees, one in each line.

Example:

cn=barcelona,dc=my-company,dc=com

cn=madrid,dc=my-company,dc=com

Group Search Attributes:

These attributes are used when a search

for groups with a search string is done.

This happens, for instance, in the share

dialogue. By default the group display

name attribute as specified above is

being used. Multiple attributes can be

given, one in each line.

Example:

cn

description

Group Member association:

The attribute that is used to indicate group

memberships, i.e. the attribute used by

LDAP groups to refer to their users.

Example: uniquemember

Special AttributesQuota Field:

ownCloud can read an LDAP attribute

and set the user quota according to

its value. Specify the attribute here,

otherwise keep it empty. The attribute

shall return human readable values, e.g.

2 GB.

Example: ownCloudQuota

Quota Default:

Override ownCloud default quota for

LDAP users who do not have a quota setin the attribute given above.

Example: 15 GB

Email Field:

ownCloud can read an LDAP attribute

and set the user email there from. Spe-

cify the attribute here, otherwise keep

it empty.

Example: mail

Page 7


8/13


User Home Folder Naming Rule:By default, the ownCloud creates the

user directory, where all files and

meta data are kept, according to the

ownCloud user name. You may want to

override this setting and name it after

an attributes value. The attribute given

can also return an absolute path, e.g. /

mnt/storage43/alice. Leave it empty for

default behavior.

Example: cn

Expert Settings(>= ownCloud 5.0.7)

In the Expert Settings fundamental

behavior can be adjusted to your needs.

The configuration should be done before

starting production use or when testing

the installation.

Internal Username:

The internal username is the identifier in

ownCloud for LDAP users. By default it

will be created from the UUID attribute.

By using the UUID attribute it is madesure that the username is unique and

characters do not need to be converted.

The internal username has the restric-

tion that only these characters are allo-

wed: [a-zA-Z0-9_.@-]. Other characters

are replaced with their ASCII correspon-

dence or are simply omitted.

The LDAP backend ensures that there

are no duplicate internal usernames

in ownCloud, i.e. that it is checking all

other activated user backends (includinglocal ownCloud users). On collisions

a random number (between 1000 and

9999) will be attached to the retrieved

value. For example, if alice exists, the

next username may be alice_1337.

The internal username is also the default

name for the user home folder in own-

Cloud. It is also a part of remote URLs,

for instance for all *DAV services. With

this setting the default behaviour can be

overriden. To achieve a similar behavi-

our as before ownCloud 5 enter the user

display name attribute in the following

field.

Leave it empty for default behaviour.

Changes will have effect only on newly

mapped (added) LDAP users.

Example: uid

Override UUID detection:

By default, ownCloud autodetects the

UUID attribute. The UUID attr ibute is

used to doubtlessly identify LDAP users

and groups. Also, the internal username

will be created based on the UUID, if not

specified otherwise above.

You can override the setting and pass

an attribute of your choice. You must

make sure that the attribute of your

choice can be fetched for both users and

groups and it is unique. Leave it empty

for default behaviour. Changes will have

effect only on newly mapped (added)

LDAP users and groups. It also will

have effect when a users or groups DN

changes and an old UUID was cached: It

will result in a new user. Because of this,

the setting should be applied before

putting ownCloud in production use and

cleaning the bindings (see below).

The default behaviour does not differ

from ownCloud 4.5. You do not want to

change this after upgrading from ownC-

loud 4.5 unless you update the mapping

tables yourself.

Example: cn

Username-LDAP User Mapping:

ownCloud uses the usernames as key

to store and assign data. In order to pre-

cisely identify and recognize users, each

LDAP user will have a internal username

in ownCloud. This requires a mapping

from ownCloud username to LDAP user.

The created username is mapped to the

UUID of the LDAP user. Additionally the

DN is cached as well to reduce LDAP in-

teraction, but it is not used for identifica-

tion. If the DN changes, the change will

be detected by ownCloud by checking

the UUID value.

Page 8


9/13


The same is valid for groups.

The internal ownCloud name is used all

over in ownCloud. Clearing the Map-

pings will have leftovers everywhere. Do

never clear the mappings in a production

environment. Only clear mappings in a

testing or experimental stage.

Clearing the Mappings is not confi-

guration sensitive, it affects all LDAP

configurations!

Testing the configuration

In this version we introduced the Test

Configuration button on the bottom of

the LDAP settings section. It will always

check the values as currently given in

the input fields. You do not need to save

before testing. By clicking on the button,

ownCloud will try to bind to the ownC-

loud server with the settings currently

given in the input fields. The response

will look like this:

In case the configuration fails, you can

see details in ownClouds log, which is

in the data directory and called ownc-

loud.log or on the bottom the Settings

Admin page. Unfortunately it requires

a reload sorry for the inconvenience.

In this case, save the settings. You can

check if the users and groups are fet-

ched correctly on the Settings Users

page.

Troubleshooting, Tips and TricksSSL Certificate Verification(LDAPS, TLS)

A common mistake with SSL certificates

is that they may not be known to PHP. If

you have trouble with certificate validati-

on make sure that

you have the certificate of the server

installed on the ownCloud server

the certificate is announced in the

systems LDAP configuration file (usu-

ally /etc/ldap/ldap.conf on Linux, C:\openldap\sysconf\ldap.conf or C:\

ldap.conf on Windows) using a TLS_

CACERT /path/to/certline.

Using LDAPS, also make sure that

the port is correctly configured (by

default 686)

Microsoft Active Directory

In case you want to connect to a Win-

dows AD, you must change some values

in the Advanced tab.

The default in User Display Name

Field will not work with Active Direc-

tory.

The Group Member association must

be set to member (AD)

Check Case insensitive LDAP server

(Windows)

Duplicating Server Configurations

In case you have a working configura-

tion and want to create a similar one or

snapshot configurations before mo-

difying them you can do the following:

1. Go to the LDAP Basic tab

2. On Server Configuration choose Add

Server Configuration

3. Answer the question Take over

settings from recent server configura-

tion? with yes.

4. (optional) Switch to Advanced tab

and uncheck Configuration Active inthe Connection Settings, so the new

configuration is not used on Save

5. Click on Save

Now you can modify the configuration

and enable it if you wish.

ownCloud LDAP Internals

Some parts of how the LDAP backend

works are described here. May it be

helpful.

User and Group Mapping

In ownCloud the user or group name is

used to have all relevant information in

the database assigned. To work reliably

a permanent internal user name and

group name is created and mapped to

the LDAP DN and UUID. If the DN changes

in LDAP it will be detected, there will be

no conflicts.

Those mappings are done in thedatabase table ldap_user_mapping

and ldap_group_mapping. The user

name is also used for the users folder

(except something else is specified in

User Home Folder Naming Rule), which

contains files and meta data.

As of ownCloud 5 internal user name and

a visible display name are separated.

This is not the case for group names,

yet, i.e. group cannot be altered.

That means that your LDAP configuration

should be good and ready before putting

it into production. The mapping tables

are filled early, but as long as you are

testing, you can empty the tables any

time. Do not do this in production. If you

want to rename a group, be very careful.

Do not rename the users internal name.

Page 9


10/13


CachingFor performance reasons a cache has

been introduced to ownCloud. He we

store all users and groups, group mem-

berships or internal userExists-requests.

Since ownCloud is written in PHP and

each and every page request (also done

by Ajax) loads ownCloud and would

execute one or more LDAP queries again,

you do want to have some of those que-

ries cached and save those requests and

traffic. It is highly recommended to have

the cache filled for a small amount oftime, which comes also very handy when

using the sync client, as it is yet another

request for PHP.

Handling with Backup Server

When ownCloud is not able to contact

the main server, he will be treated as

offline and no connection attempts will

be done for the time specified in Cache

Time-To-Live. If a backup server is con-

figured, it will be connected instead. If

you plan a maintained downtime, check

Disable Main Server for the time being to

avoid unnecessary connection attempts

every now and then.

Appendix 2:Provisioning API

The provisioning API is based on the

Cloud section of the Open Collaboration

Services 1.7 draft specification. The fol-

lowing appendix outlines the available

services, and provides examples for how

to interact with this service. Simply ena-

ble the app in the admin control panel in

ownCloud, and the API will be accessible

to end users.

Architecture Overview

REST

We use REST for the webservices calls.

Unlike, for example SOAP, REST is

very, lightweight, easy to learn and

implement and cachable. REST is very

widespread in the internet and is used

by other popular webservices. REST

support is integrated into various web or

desktop frameworks and it is platform

and technology independent The dataexchange format is XML. If you add the

format=json parameter you can also get

the data in JSON format.

SSL

We suggest to use ssl to encrypt the

data transfer between client and service

providers. unencrypted data transfer is

also possible when a SSL it too expensi-

ve or slow.

AuthenticationMost services require an authenticated

user. This is important for legal reasons,

and to prevent DOS attacks. At the

moment we support authentication via

login/password or an API key.

example login/password

https://frank:[email protected]

desktop.org/v1/activity?page=3

example API key

https://

API5142830791365744186814934@api.

opendesktop.org/v1/activity?page=3

Proxy

It is possible to implement a proxy ser-

vice provider to integrate other proprie-

tary webservices.

Date Format

All date and time data is in ISO 8601

format.

Services

The applications or websites do not have

to support every service. We suggest

to implement only the services into the

clients or service providers which are

useful for the users at this point.

At the moment there are the following

services:

CONFIG

ERSON

FRIEND

MESSAGE

ACTIVITY

CONTENT

FAN

KNOWLEDGEBASE

EVENT

COMMENTS

PRIVATE DATA FORUM

...more to come later

Error Reporting

Every response xml contains a status,

statuscode and a message tag. The

status tag has only two possible values.

ok or failed. If the status is failed

you can get a human readable errortext

from the message tag. Examples of

errormessages are: data is private or

Page 10


11/13


12/13


user / get private keyReads the private key of the user. Only

authenticated users are allowed to

access this method and the user will

always get access to his private key only.

Authentication is done by sending a

Basic HTTP Authorisation header.

syntax: /v1/cloud/privatekey

HTTP method: GET

Statuscodes:

* 100 - successfull

* 404 - key does not exist

* 300 - encryption not enabled

Example: GET http://

frank:[email protected]/ocs/

v1.php/cloud/privatekey

Reads the private key for a user.

Example: [[!format txt ok 100 treThi-

sistheprivatekeyoffrank654fhfghf

]]

user / get file key

Reads the file encryption key of the file.Only authenticated users are allowed

to access this method and the user will

always get access to his private key only.

Authentication is done by sending a

Basic HTTP Authorisation header.

syntax: /v1/cloud/file/file/filekey

HTTP method: GET

Statuscodes:

* 100 - successfull

* 404 - key does not exist


Example: GET http://


v1.php/cloud/le/path%2Fto%2Fle.

txt/lekey

Reads encryption key of the file.

Example: [[!format txt ok 100 encrypti-

onkeyforgivenle ]]

user / set public keyWrites public key of the user to the

server. Only authenticated users are

allowed to access this method. Authen-

tication is done by sending a Basic HTTP

Authorisation header.

syntax: /v1/cloud/publickey

HTTP method: POST

Statuscodes:

* 100 - successfull

* 404 - could not write public key to

server


Example: POST http://

frank:[email protected]/

ocs/v1.php/cloud/publickey -d

key=publickeyoftheuser

Write public key to the server.

Example: [[!format txt ok 100 ]]

user / set private key

Writes private key of the user to the

server. Only authenticated users areallowed to access this method. Authen-

tication is done by sending a Basic HTTP


syntax: /v1/cloud/privatekey

HTTP method: POST

Statuscodes:

* 100 - successfull

* 404 - could not write private key to

server



frank:[email protected]/

ocs/v1.php/cloud/privatekey -d

key=privatekeyoftheuser

Write private key to the server.


user / set file key

Writes file encryption key of the file to

the server. Only authenticated users are

allowed to access this method. Authen-tication is done by sending a Basic HTTP


syntax: /v1/cloud/filekey

HTTP method: POST

Statuscodes:

* 100 - successful

* 404 - could not write file key to

server



frank:password@myowncloud.

org/ocs/v1.php/cloud/lekey -dkey=lekeyofthele -d le=le/

to/which/the/key/belongs

Write file encryption key to the server.


users / adduser

Create a new user on the cloud server.

Only authenticated administrator users

are allowed to access this method. Au-

thentication is done by sending a Basic

HTTP Authorisation header. syntax: /v1/cloud/users

HTTP method: POST

POST argument: userid - string, the

required username for the new user

POST argument: password - str ing,

the required password for the new

user

Statuscodes:

* 100 - successful

* 101 - invalid input data

* 102 - username already in user

* 103 - unknown error occurred whilstadding the user



v1.php/cloud/users -d user=Frank

-d password=frankspassword

Creates the user Frank with password

frankspassword


Page 12


13/13

ownCloud, Inc.

10 Foster Road

Lexington, MA 02421

United States

mail: [email protected]

phone: +1 (877) 394-2030

https://www.owncloud.com

Oc5 Enterprise Appliance Tour

Documents