diff --git a/HOWTO.rst b/HOWTO.rst new file mode 100644 index 000000000..9c7912c80 --- /dev/null +++ b/HOWTO.rst @@ -0,0 +1,361 @@ +Writing Documentation for ownCloud +================================== + +In order to improve ownCloud's documentation, the +documentation repository has been created. This allows +everyone to contribute. Even though or particularly +because it is now a lot easier to contribute to +documentation, it is important that everyone +obeys certain principles + +1. in terms of technicalities, such as dealing with Git, + learning reStructuredText, etc. +2. in terms of writing the actual documentation, + i.e. writing style, choosing examples, + structuring new texts, etc. + +Getting Started with the Documentation Repository +------------------------------------------------- + +You have two basic choices, editing the manual `directly +on GitHub`_, or checking out the sources. If you want to +use direct editing, please make sure to pick "stable45" (or +whatever the latest stable branch is) from the branch selector +before proceeding. If you want to check out the documentation +locally, follow these steps: + +1. Check out ``git://github.com/owncloud/documentation`` +2. Select the branch that you want to edit. Check out the + ``Policy`` section to know which branch is right for you. + Usually, it's the latest stable branch, i.e. ``git checkout stable45`` + if the latest stable ownCloud version is 4.5. +3. Find the manual you want to edit, pick the correct .rst file and + start working. Check the next section about target audiences! +4. Run "make html" and "make latexpdf" (requires a full LaTeX installation!) + to verify you have not broken anything. +5. Commit your work, if you have write access to ownCloud, or create a pull + request otherwise. +6. If you have committed the work yourself, please merge the result + into the master branch: + + :: + + git fetch origin + git checkout master + git merge origin/stable45 master + + git add + git commit + git push + +For editing, you will need to learn reStructuredText. It's a simple markup, but +it's usually not known by heart, contrary to e.g. HTML. Thus, I recommend printing +this `RST Cheat Sheet`_, and keep the `reStructuredText Primer`_ as well as the +`reStructuredText User Documentation`_ in your bookmarks. + +Dependencies for Building the Documentation locally +--------------------------------------------------- + +ownCloud documentation uses Sphinx_, a Python-based documentation framework. You +will need: + +* Python 2.6 or newer +* Sphinx_ for Python 2.x (usually part of any Linux distribution or in Mac-Ports) +* sphinxcontrib-phpdomain_ (install via ``pip install sphinxcontrib-phpdomain``) +* texlive-latex (for building PDFs via LaTeX). Debian users need to install texlive-latex-full. + +.. _Sphinx: http://sphinx-doc.org +.. _sphinxcontrib-phpdomain: http://pypi.python.org/pypi/sphinxcontrib-phpdomain + +Target Audiences +---------------- + +**Admin Manual** + This does not only include professional admins, but simply everyone who wishes + to setup an ownCloud instance. In case of doubt, make sure to let the reader + know about your terminology, at least in the basic chapters. If you are going + into the nitty-gritty of fail-over, load-balancing and the like, a bit more + tech-literacy can be assumed, but try to provide helpful links nonetheless. + +**User Manual** + This manual describes the Web UI as well as other exposed functionality, + such as WebDAV, calendar, etc. It does *not* include the ownCloud Desktop + Client, which has its `own manual`_ embedded in its repository. + +**Developers Manual** + Be aware that, depending on the chapter, this can address people who develop + the ownCloud core, or those who develop apps using the ownCloud framework. + Either way, try to not assume too much knowledge, to ease the learning + curve. + +Writing Style +------------- + +Documentation should be concise and to the point, maintaining a consistent +style. Here is some advise on what to watch out for when contributing. + +**Know what you are writing about** + While this sounds obvious, this poses a challenge to both novice and + professional writers alike, because writing good documentation requires a + solid understanding of the problem at hand. However, documentation writers + usually only know aspects, i.e. they may be able to use the software, + but they are not *domain experts*. It is an essential part of their job + to get in touch with the domain experts to get the big picture, and + then write the documentation. + + Making sure you have acquired all necessary knowledge is thus essential. + Whenever you find yourself writing sentences like "you should know how this + works", you are clearly skipping relevant information. This is when you + should either try to get more information to describe the information + properly, or at least link to a generic problem solution on an external site. + A halfhearted documentation is not only unhelpful, it's usually frustrating. + +**Be honest about what we do not cover yet** + The only other box markup allowed in the ownCloud + documentation is ``todo::``. If you discover imprecise our out-of-date + documentation, add a todo marker describing what is missing, so it can be + fixed by doc writing volunteers. Often, these make great Junior Jobs. + However, make sure it does not become an ever-growing wish list. + +**Do not try to sell the product** + People reading the documentation are *already* showing interest and the best + way to have them using ownCloud is to help them with their issue on a purely + technical level. They will be put off by noisy claims that do not help them. + You are not a copy-writer [1]_, maintain a neutral style. + +**Avoid redundancy** + Consider this part that actually used to be part of the documentation [2]_: + + Next, choose ``Basic Server Configuration``. As you obviously have guessed by + now, this will install the basic configuration of the server. + + Not only does this force the reader to parse the anecdotal clause (which does + not explain anything): He will either know what this option does, and thus be + annoyed by the redundant information, or he will *not* have guessed it. This + reader will not only take offense, but the text also does not teach him what + a basic server configuration is, leaving him non the wiser. + +**Do not write prose** + Prefer bullet points over long textual lists for enumeration, do not try + to write complicated grammatical constructs. It's better to provide an + example and explain its details than describing the problem in an overly + abstract way. You are not a poet [1]_! + +**Avoid smileys/emoticons** + They usually exhibit an actual or perceived lack of your knowledge on the + topic: + + You should know how to configure Apache ;-) + + They can also be an attempt to inappropriately bond with the user (remember, + they seek information, not entertainment. You are not a novelist either + [1]_!) + + We are all too familiar with problems like these ;-) + + If you are guiding the user through a scenario, the use of "we" is + acceptable. ("Next, we have to pick an appropriate caching strategy"), but + should not be overused. + +**Do not use "don't"** + For native speakers this should go without saying: Given the books formal + nature, informal wording should not be used. This also includes other + abbreviations such as "haven't", "shouldn't", "it's", "that's", etc. + Instead, use "do not", "have not", "should not", "it is " "that is" etc. + Similarly, avoid street style language, i.e. do not write "u" but "you". + +**Try to address the reader directly, but do not try to bond too strongly** + Indirection, while sometimes elegant, makes a text harder to read: + + The ``upload_max_size`` directive can be used to define an upper bound + for the upload. + + Compare this to: + + If you want to restrict the upload, use the ``upload_max_size`` directive... + + which is a lot easier to read. Avoid the first person narration, as it easily + creates an author vs reader scenario, like so [2]_: + + I have not installed the ``php5-intl`` extension. You might want to install it. + + This creates a subjective perspective, and - more importantly - disguises + exactly *why* the reader might want to install it even though you did not. + +**Know your reader** + Provide documentation with a user story in mind. Try to picture situations + in which people might most frequently consult your documentation. This has + immediate consequences on the way you are describing things. Picture most + Installation scenarios: in a data center, on a home NAS or in an ISP-rented + virtual server, advising the user to check the installation by typing + ``http://localhost/owncloud`` makes no sense. They will most likely not + be sitting in front of the server, but test remotely, even though your + test installation might in fact be installed locally. + +**Provide examples** + After providing a bit of theory, complex topics should always be accompanied + by a meaningful but concise examples. An example is the ideal starting point + for further explanation. + +**Provide schematics** + "One Picture is Worth Ten Thousand Words". The more complex the topic, the + more people will appreciate being presented with the literal "big picture". + Inkscape_ is a great tool for drawing and exporting schematics. It is a good + idea to export both PDF and PNG, since PDF will go better with inside PDF. + Let Sphinx decide which format to use by writing ``Image:: MyImage.*`` + +**Provide screenshots** + Especially for end user documentation, screenshots are a vital way for + readers to match the description with what they see on the screen. + +**Use figures rather than image tags** + Figures (``figure::``) are special environments that contain images + and schematics, rather than ``image::``. Backends like LaTeX will be + able to position figures in meaningful places in the PDF version. + Use the ``:ref:`` instruction to reference them in the text. Figures + allow for captions, use them to provide context! + +**Avoid the Wall of Text** + Make use of paragraphs. Paragraphs should be no longer than four + sentences. More than five paragraphs in a row indicate a lack + of examples, schematics or pictures. + +**Do not overuse boxes** + reStructuredText offers a lot of boxes: Warnings, Notes, + etc. You can even define your own! However, this usually leads to an + avalanche of boxes, which significantly disturbs the reading flow. Thus, only + use the ``note::`` markup when you really want to point out odd behavior. + Avoid ``warning::`` and other markups. the note markup should be indicative + of something special. Otherwise, try to keep the reader in his text flow, + e.g.: + + ... for the Apache web server, you should use a ``.htaccess`` file. + .. note:: ``.htaccess`` files are specific to Apache and usually will not + work on other web servers. + + this is better written as: + + ... for the Apache web server, you should use a ``.htaccess`` file. + In case you are not using apache, the section :ref: `Web Server Notes` + will explain how to implement alternatives to this Apache-proprietary + way of securing your data directory. + +**Do not overuse headings** + If you find yourself requiring fourth or fifth-level headings, you are + probably doing something wrong. Headings are a great way to structure + a chapter or section before you start to fill them with content, but you + should reconsider their necessity if you find yourself nesting too much + or if lots of headings guard a single paragraph. + +**Wrap your text at 80 characters** + This makes markup like reStructuredText a lot easier to read. Most editors have + support for this. Given the sheer amount of preferred text editors, the most + effective way to figure out how to set this up is an online search, which will + reveal tips such as the answers to `this stackoverflow question`_. + +**Be consistent about numbers** + Single digits (0-9) should be written out ("In a Scenario involving two + servers..."). For the rest, use numerals ("This solution will scale + up to 1000 concurrent users"). However, stay consistent when you need + use single and multi-digit numbers to refer to the same subject in a + sentence: "This clustering solution scales up from 2 to 20 servers". + In case of doubt, refer to the full grammar rule set on `writing + numbers`_. + +**Use title case sentences for headings** + This means that headings should obey + to the following rules [3]_: + +1. Capitalize the first word of the title/heading and of any + subtitle/subheading. +2. Capitalize all "major" words (nouns, verbs, + adjectives, adverbs, and pronouns) in the title/heading, including the + second part of hyphenated major words (e.g., Self-Report not Self-report). +3. Capitalize all words of four letters or more. + + Consider the following heading: + + *Hardening ownCloud for secure deployment* + + This should be written as: + + *Hardening ownCloud for Secure Deployment* + +**Check your spelling** + Always. No exceptions, no excuses. Everything has a built-in spell checker + these days. + + **Check for stray and trailing spaces** + A ``git diff`` will reveal them, as will most editors, if set up correctly. This + page describes how to `set up vim to spot unwanted spaces`_. + +**Find a human reviewer** + This can be any person within the community, or a person familiar with the topic. + Let them try to comprehend what you just wrote. If they don not get it, an average + user most likely will not either. A reviewer will also spot grammar errors, + which the spell checker can not usually catch. + + Ideally, we would even have editors. Note that an editor does a lot more than + reviewing. He will do rewrites, style sanitation, consistency checks, etc. + Unfortunately, we so far (at the time of writing) do not have any + volunteering professional writers who could serve as editors, so we all need + to make sure that at least the style is consistent. This is especially + important when you are adding content to existing documentation. + +That is it. If you are looking for further inspiration on good writing style, +check the FAQ in the next section. Thank you for improving the ownCloud +documentation. + +Frequently Asked Questions +-------------------------- + +**What should I look at as a reference for good documentation style?** + The `Sphinx documentation`_ itself is + very good. Every page has a "Show source" section that shows how it was typeset. + Another great example is the `Subversion Book`_. + +**I need to create a new chapter, should I create chapter.rst or chapter/index.rst?** + Do not create a directory. We can still re-factor into a directory later on. + If you are sitting on a huge pile of documentation on a single topic, + we will be glad to assist. Please send a mail to the `ownCloud mailinglist`_ + +**Why not use cherry-picking from master to the stable branch?** + Cherry-picking only works if we have someone who makes sure the cherries + actually get picked. This also involves adjusting the documentation to + stable45, which requires domain specific knowledge of both versions. If you + still would like to volunteer, speak up. + +**LaTeX fails to render my fancy table. What can I do to fix this?** + Avoid overly complex tables. Complex tables should usually broken down into + simple tables + text anyway. Remember, people might read this on their eBook + reader! Everything with multiline columns is something that the LaTeX generator + frowns upon. In general though, the LaTeX generator is just a lot more picky + over a broken ASCII table art misplacement than the HTML equivalent is. + Double-check your markup. If you really need complex tables, consider CSV + tables. + +**I have pushed changes to the documentation repo, what now?** + `Mr Jenkins`_ will try to build HTML and PDF versions and put them online at + the `ownCloud doc server`_. If he fails to build your version, you will + receive a mail, please fix it or ask for help on IRC (irc.freenode.net, + #owncloud-dev) or the `ownCloud mailinglist`_. + +.. [1] For the purpose of editing this documentation anyway. +.. [2] Actual real-life example. Slightly modified to protect the innocent. +.. [3] As described on the `APA style blog`_. + +.. _this stackoverflow question: http://stackoverflow.com/questions/3033423/vim-command-to-restructure-force-text-to-80-columns +.. _directly on github: https://github.com/owncloud/documentation +.. _Mr Jenkins: http://ci.tmit.eu +.. _ownCloud doc server: http://doc.owncloud.com +.. _RST Cheat Sheet: http://github.com/ralsina/rst-cheatsheet/raw/master/rst-cheatsheet.pdf +.. _reStructuredText Primer: http://sphinx-doc.org/rest.html +.. _reStructuredText User Documentation: http://docutils.sourceforge.net/rst.html +.. _own manual: https://github.com/owncloud/mirall/tree/master/doc +.. _Inkscape: http://www.inkscape.org +.. _set up vim to spot unwanted spaces: http://vim.wikia.com/wiki/Highlight_unwanted_spaces +.. _ownCloud mailinglist: mailto:owncloud@kde.org +.. _writing numbers: http://www.grammarbook.com/numbers/numbers.asp +.. _Sphinx documentation: http://sphinx-doc.org/contents.html +.. _Subversion Book: http://svnbook.red-bean.com/ +.. _APA style blog: http://blog.apastyle.org/apastyle/2012/03/title-case-and-sentence-case-capitalization-in-apa-style.html diff --git a/admin_manual/auth_ldap.rst b/admin_manual/auth_ldap.rst index c57167e61..d1288d73e 100644 --- a/admin_manual/auth_ldap.rst +++ b/admin_manual/auth_ldap.rst @@ -6,7 +6,7 @@ logging in with LDAP credentials including: * LDAP group support * File sharing with users and groups -* Access via WebDAV and of course ownCloud Desktop Clien +* Access via WebDAV and of course ownCloud Desktop Client * Versioning, external Storages and all other ownCloud Goodies To connect to an LDAP server the configuration needs to be set up properly. @@ -26,7 +26,7 @@ LDAP server and use it with ownCloud. LDAP Basic Settings -Note that a hint will be shown on the right handside, when hovering with the +Note that a hint will be shown on the right hand side, when hovering with the mouse over an input field. This gives you more context information while filling out the settings. @@ -34,14 +34,14 @@ Settings Details ~~~~~~~~~~~~~~~~ Host: - The hostname of the LDAP server. It can also be a ``ldaps://`` URI, for + The host name of the LDAP server. It can also be a ``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. - Seperated Base DNs for users and groups can be set in the Advanced + Separated Base DNs for users and groups can be set in the Advanced tab. Nevertheless, this field is mandatory. * *Example: dc=my-company,dc=com* @@ -59,10 +59,10 @@ Password: User Login Filter: The filter to use when a users tries to login. Use ``%uid`` as placeholder - for the username. Note, that login applies this filter only, but not User + 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 username and email adress): ``(|(uid=%uid)(email=$uid))`` + * 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. @@ -81,7 +81,7 @@ Advanced Settings In 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 specifiy distinguished bases for user and group searches. +to specify distinguished bases for user and group searches. .. figure:: images/ldap-advanced-settings-oc451.png @@ -111,13 +111,13 @@ Group Member association: * Example: uniquemember Use TLS: - Wether to use TLS encrypted connection to the LDAP server. - In case you use SSL connections (via ldaps) do not check it, it will fail. + Wether to use TLS encrypted connection to the LDAP server. In case you use + SSL connections (via the ldaps scheme) do not check it, it will fail. * Example: [ ] Case insensitive LDAP server (Windows): - Wether theLDAP server is running on a Windows Host + Wether the LDAP server is running on a Windows Host * Example: [ ] @@ -128,9 +128,9 @@ Turn off SSL certificate validation: * Example: [ ] User Display Name Field: - The attribute that should be used as ownCloud username. ownCloud allows + The attribute that should be used as ownCloud user name. ownCloud allows a limited set of characters ``(a-zA-Z0-9.-_@)``, every other character - will be replaced in ownCloud. Once a username is assigned, it will not be + will be replaced in ownCloud. Once a user name is assigned, it will not be changed, i.e. changing this value will only have effect to new LDAP users. The default, uid, does not exist in AD, switch to ``cn``, for example, otherwise you will not see any users. @@ -138,11 +138,10 @@ User Display Name Field: * Example: displayName Group Display Name Field: - The attribute that should be used as ownCloud - groupname. ownCloud allows a limited set of characters (a-zA-Z0-9.-_@), every - other character will be replaced in ownCloud. Once a groupname is assigned, it - will not be changed, i.e. changing this value will only have effect to new - LDAP groups. + 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`` @@ -151,7 +150,7 @@ Quota Attribute: there from. Specify the attribute here, otherwise keep it empty. * Example: ownCloudQuota - * formerly Quota Field in oC 4.0 + * formerly Quota Field in ownCloud 4.0 Quota Default: Override ownCloud default quota for LDAP users who do not @@ -167,7 +166,7 @@ Email Attribute: Cache Time-To-Live: We introduced a cache to avoid unnecessary LDAP traffic, - for example lookups check wether the users exists on every page request or + 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. Changing this setting empties the Cache. The time is given in seconds. @@ -177,7 +176,7 @@ Cache Time-To-Live: 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 - username. You may want to override this setting and name it after an + user name. You may want to override this setting and name it after an attribute’s value. Once set for a user, the user name folder will not change, i.e. changing this value will only have effect to new LDAP users. Leave it empty to default behaviour @@ -198,7 +197,7 @@ 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 testíng. By clicking +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 ownCloud server with the settings currently given in the input fields. The response will look like this: @@ -206,7 +205,7 @@ settings currently given in the input fields. The response will look like this: Failure -In case the configuration fails, you can see details in ownCloud’s log, which +In case the configuration fails, you can see details in ownCloud's log, which is in the data directory and called ``owncloud.log`` or on the bottom the ``Settings → Admin page``. Unfortunately it requires a reload – sorry for the inconvenience. @@ -226,15 +225,15 @@ Some parts of how the LDAP backend works are described here. May it be helpful. User and Group Mapping ---------------------- -In ownCloud, the username is automatically the user ID, same applies for +In ownCloud, the user name is automatically the user ID, same applies for groups. That’s why we map the DN and UUID of the LDAP object to an ownCloud name. Those mappings are done in the database table ldap_user_mapping and -ldap_group_mapping. The username is also used for the user’s folder, which +ldap_group_mapping. The user name is also used for the user’s folder, which contains files and meta data. Most ownCloud applications, like Sharing, use the -username to refer to a user. Renaming a user (or a group) is not supported. +user name to refer to a user. Renaming a user (or a group) is not supported. 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 empty the tables any time. Don’t do this in production. If you +testing, you empty the tables any time. Do not do this in production. If you want to rename a user or a group, be very careful. Caching @@ -242,7 +241,7 @@ Caching For performance reasons a cache has been introduced to ownCloud. He we store all users and groups, group memberships or internal userExists-requests. Since -ownCloud is written in PHP and each and every page rerquest (also done by Ajax) +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 queries cached and save those requests and traffic. It is highly recommended to have the cache filled for a small amount of time, which diff --git a/admin_manual/conf.py b/admin_manual/conf.py index 713be4fb7..f40907e06 100644 --- a/admin_manual/conf.py +++ b/admin_manual/conf.py @@ -25,7 +25,8 @@ import sys, os # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = [] +extensions = ['sphinxcontrib.phpdomain', 'sphinx.ext.todo'] + # Add any paths that contain templates here, relative to this directory. templates_path = ['../_shared_assets/templates'] diff --git a/admin_manual/custom_mount_config.rst b/admin_manual/custom_mount_config.rst new file mode 100644 index 000000000..6508ab42c --- /dev/null +++ b/admin_manual/custom_mount_config.rst @@ -0,0 +1,202 @@ +Custom Mount Configuration +========================== + +Since ownCloud 4.0 it is possible to configure the filesystem to mount external +storage providers into ownCloud's virtual file system. You can configure the +file system by creating and editing ``/config/mount.php``, the configuration +file holds a PHP array configuring 2 types of entries: + +- **Group mounts:** each entry configures a mount for each user in group. +- **User mounts:** each entry configures a mount for a single user or for all + users. + +For each type, there is an array with the user/group name as key, and an array +of configuration entries as value. Each entry consist of the class name of the +storage backend and an array of backend specific options. The template +``$user`` can be used in the mount point or backend options. As of writing the +following storage backends are available for use: + +- Local file system +- FTP +- WebDAV +- `OpenStack Swift`_ +- SMB + +Example +~~~~~~~ + +.. code-block:: php + + array( + 'admin'=>array( + '/$user/files/Admin_Stuff'=>array( + 'class'=>'OC_Filestorage_Local', + 'options'=>array(...) + ), + ), + ), + 'user'=>array( + 'all'=>array( + '/$user/files/Pictures'=>array( + 'class'=>'OC_Filestorage_DAV', + 'options'=>array(...) + ), + ), + 'someuser'=>array( + '/someuser/files/Music'=>array( + 'class'=>'OC_Filestorage_FTP', + 'options'=>array(...) + ), + ), + ) + ); + +Backends: +--------- + +Local Filesystem +~~~~~~~~~~~~~~~~ + +The local filesystem backend mounts a folder on the server into the +virtual filesystem, the class to be used is ``OC_Filestorage_Local`` and +takes the following options: + +- ``datadir`` : the path to the local directory to be mounted. + + +Example +^^^^^^^ + +.. code-block:: php + + array( 'class'=>'OC_Filestorage_Local', + 'options'=>array( 'datadir'=>'/mnt/additional_storage' ) + )`` + +.. note:: You must ensure that the web server has sufficient permissions on the + folder. + +FTP +~~~ + +The FTP backend mounts a folder on a remote FTP server into the virtual +filesystem and is part of the ‘External storage support’ app, the class +to be used is ``OC_Filestorage_FTP`` and takes the following options: + +- ``host``: the hostname of the ftp server. +- ``user``:the username used to login on the ftp server +- ``password``: the passwordt to login on the ftp server +- ``secure``: whether to use ftps:// to connect to the ftp server instead + of ftp:// (optional, defaults to false) +- ``root``: the folder inside the ftp server to mount (optional, defaults + to ‘/’) + +Example +^^^^^^^ + +.. code-block:: php + + array( 'class'=>'OC_Filestorage_FTP, + 'options'=>array ( + 'host'=>'ftp.myhost.com', + 'user'=>'johndoe', + 'password'=> 'secret', + 'root'=>'/Videos') + ) + +.. note: PHP needs to be build with FTP support for this backend to work. + +WebDAV +~~~~~~ + +The WebDAV backend mounts a folder on a remote WebDAV server into the +virtual filesystem and is part of the ‘External storage support’ app, +the class to be used is ``OC_Filestorage_DAV``\ and takes the following +options: + +- ``host``: the hostname of the webdav server. +- ``user``: the username used to login on the webdav server +- ``password``: the passwordt to login on the webdav server +- ``secure``: whether to use https:// to connect to the webdav server + instead of http:// (optional, defaults to false) +- ``root``: the folder inside the webdav server to mount (optional, + defaults to ‘/’) + +Example +^^^^^^^ + +.. code-block:: php + + array( 'class'=>'OC_Filestorage_DAV, + 'options'=>array( + 'host'=>'myhost.com/webdav.php', + 'user'=>'johndoe', + 'password'=>'secret', + 'secure'=>true) + ) + +OpenStack Swift +~~~~~~~~~~~~~~~ + +The Swift backend mounts a container on an OpenStack Object Storage +server into the virtual filesystem and is part of the ‘External storage +support’ app, the class to be used is ``OC_Filestorage_SWIFT``\ and +takes the following options: + +- ``host``: the hostname of the authentication server for the swift + storage. +- ``user``: the username used to login on the swift server +- ``token``: the authentication token to login on the swift server +- ``secure``: whether to use ftps:// to connect to the swift server instead + of ftp:// (optional, defaults to false) +- ``root``: the container inside the swift server to mount (optional, + defaults to ‘/’) + +Example +^^^^^^^ + +.. code-block:: php + + array( 'class'=>'OC_Filestorage_SWIFT, + 'options'=>array( + 'host'=>'swift.myhost.com/auth', + 'user'=>'johndoe', + 'token'=>'secret', + 'root'=>'/Videos', + 'secure'=>true ) + ) + +SMB +~~~ + +The SMB backend mounts a folder on a remote Samba server, a NAS appliance or a +Windows machine into the virtual file system. It is part of the ‘External +storage support’ app, the class to be used is ``OC_Filestorage_SMB``\ and +takes the following options: + +- ``host``: the host name of the samba server. +- ``user``: the user name used to login on the samba server +- ``password``: the password to login on the samba server +- ``share``: the share on the samba server to mount +- ``root``: the folder inside the samba share to mount (optional, defaults + to ‘/’) + +.. note:: The SMB backend requires ``smbclient`` to be installed on the server. + +Example +^^^^^^^ + +.. code-block:: php + + array( 'class'=>'OC_Filestorage_SMB, + 'options'=>array ( + 'host'=>'myhost.com', + 'user'=>'johndoe', + 'password'=> 'secret', + 'share'=>'/test', + '/Pictures' ) + ) + +.. _OpenStack Swift: http://openstack.org/projects/storage/ diff --git a/admin_manual/custom_user_backend.rst b/admin_manual/custom_user_backend.rst new file mode 100644 index 000000000..b5eb8a109 --- /dev/null +++ b/admin_manual/custom_user_backend.rst @@ -0,0 +1,76 @@ +Custom User Backend Configuration +================================= + +Starting with ownCloud 4.5 is possible to configure additional user backends +in ownCloud's configuration file (config/config.php) using the following +syntax: + + :: + + 'user_backends'=>array( + array( + 'class'=>..., + 'arguments'=>array(...) + ) + ) + +Currently the “External user support” (user_external) app supports the +provides the following user backends: + +IMAP +~~~~ + +Provides authentication against IMAP servers + + - **Class:**\ OC_User_IMAP + - **Arguments:**\ a mailbox string as defined `here`_ + - **Example:** + + :: + + 'user_backends'=>array( + array( + 'class'=>'OC_User_IMAP', + 'arguments'=>array('{imap.gmail.com:993/imap/ssl}INBOX') + ) + ) + + + +SMB +~~~ + +Provides authentication against Samba servers + + - **Class:**\ OC_User_SMB + - **Arguments:**\ the samba server to authenticate against + - **Example:** + + :: + + 'user_backends'=>array( + array( + 'class'=>'OC_User_SMP', + 'arguments'=>array('localhost') + ) + ) + +FTP +~~~ + +Provides authentication against FTP servers + + - **Class:**\ OC_User_FTP + - **Arguments:**\ the FTP server to authenticate against + - **Example:** + + :: + + 'user_backends'=>array( + array( + 'class'=>'OC_User_FTP', + 'arguments'=>array('localhost') + ) + ) + +.. _here: http://www.php.net/manual/en/function.imap-open.php diff --git a/admin_manual/images/ucsint.png b/admin_manual/images/ucsint.png new file mode 100644 index 000000000..cc02c5132 Binary files /dev/null and b/admin_manual/images/ucsint.png differ diff --git a/admin_manual/images/ucsint1.png b/admin_manual/images/ucsint1.png new file mode 100644 index 000000000..5cca1d8a9 Binary files /dev/null and b/admin_manual/images/ucsint1.png differ diff --git a/admin_manual/images/ucsint2.png b/admin_manual/images/ucsint2.png new file mode 100644 index 000000000..8c8a286d7 Binary files /dev/null and b/admin_manual/images/ucsint2.png differ diff --git a/admin_manual/images/win7features.jpg b/admin_manual/images/win7features.jpg new file mode 100644 index 000000000..ab0e60561 Binary files /dev/null and b/admin_manual/images/win7features.jpg differ diff --git a/admin_manual/images/winserverroles.jpg b/admin_manual/images/winserverroles.jpg new file mode 100644 index 000000000..159cfbf51 Binary files /dev/null and b/admin_manual/images/winserverroles.jpg differ diff --git a/admin_manual/index.rst b/admin_manual/index.rst index 02ef5d778..792f60473 100644 --- a/admin_manual/index.rst +++ b/admin_manual/index.rst @@ -7,10 +7,12 @@ Contents :maxdepth: 2 introduction - installation + installation update auth_ldap xsendfile + custom_mount_config + custom_user_backend .. add more chapters diff --git a/admin_manual/installation.rst b/admin_manual/installation.rst index 7dd9379fb..ac0d354cb 100644 --- a/admin_manual/installation.rst +++ b/admin_manual/installation.rst @@ -1,94 +1,17 @@ Installation ============ -.. todo:: Update the dependencies to 4.5 dependencies +This chapter will introduce you to the installation of ownCloud in different +scenarios. -To run ownCloud, your webserver must have the following installed: +If you want to just try ownCloud in a virtual machine without any configuration, +skip ahead to the appliance section, where you will find ready-to-use images. -* php5 (>= 5.3) -* php5-json -* php-xml -* php-mbstring -* php5-zip -* php5-gd +.. include:: installation_source.rst +.. include:: installation_linux.rst +.. include:: installation_webservernotes.rst +.. include:: installation_macos.rst +.. include:: installation_windows.rst +.. include:: installation_ucs.rst +.. include:: installation_appliance.rst -And as *optional* dependencies: - -* php5-sqlite (>= 3) -* curl -* libcurl3 -* libcurl3-dev -* php5-curl -* php-pdo - -Commands for Ubuntu and Debian: -.. todo:: Document other distros (Windows, Mac?) - -:: - - apt-get install apache2 php5 php5-json php-xml php-mbstring php5-zip php5-gd - apt-get install php5-sqlite curl libcurl3 libcurl3-dev php5-curl php-pdo - -You don’t need any WebDAV support of your webserver (i.e. apache’s mod_webdav) -to access your ownCloud data via WebDAV, ownCloud has a WebDAV server built in. - -Extract ownCloud and copy to your webserver -------------------------------------------- - -:: - - tar -xjf path/to/downloaded/owncloud-x.x.x.tar.bz2 - cp -r owncloud /path/to/your/webserver - -Set the directory permissions ------------------------------ - -The owner of your webserver must own the apps/, data/ and config/ directories -in your ownCloud install. You can do this by running the following command for -the apps, data and config directories: - -:: - - chown -R www-data:www-data /path/to/your/owncloud/install/data - -Replace ``www-data:www-data`` with the user and group of the owner of your -webserver. - -.. note:: The ``data/`` directory will only be created after setup has run - (see below) and is not present by default in the tarballs. - -Enable .htaccess and mod_rewrite if running apache --------------------------------------------------- - -If you are running the apache webserver, it is recommended that you enable -``.htaccess`` files as ownCloud uses them to enhance security and allows -you to use webfinger. To enable .htaccess files you need to ensure that -``AllowOverride`` is set to ``All`` in the ``Directory /var/www/`` section of -your virtual host file. This is usually in ``/etc/apache2/sites-enabled/000-default``. -You should also run ``a2enmod rewrite`` and ``a2enmod headers``. Then restart -apache: service apache2 restart (for Ubuntu systems). In order for the maximum -upload size to be configurable, the .htaccess file in the owncloud folder needs -to be made writable by the server. - -Follow the install wizard -------------------------- - -Open your web browser and navigate to your ownCloud instance. If you are -installing ownCloud on the same machine as you will access the install -wizard from, the url will be: http://localhost/ (or http://localhost/owncloud). -For basic installs we recommend SQLite as it is easy to setup (ownCloud will do -it for you). For larger installs you should use MySQL or PostgreSQL. Click on the -Advanced options to show the configuration options. You may enter admin -credentials and let ownCloud create its own database user, or enter a -preconfigured user. If you are not using apache as the webserver, please set -the data directory to a location outside of the document root. See the advanced -install settings. - -Finished! ---------- - -Login and start using ownCloud! For more details on configuring -your ownCloud, please visit the Support Centre. If you plan on using the -Webfinger app and your ownCloud installation is not in the webroot then you’ll -have to manually link ``/var/www/.well-known`` to -``/path/to/your/owncloud/.well-known``. diff --git a/admin_manual/installation_appliance.rst b/admin_manual/installation_appliance.rst new file mode 100644 index 000000000..ef6be081e --- /dev/null +++ b/admin_manual/installation_appliance.rst @@ -0,0 +1,34 @@ +Appliances +---------- + +If you are looking for virtual machine images, check the Software Appliances +section. The Hardware Appliances section is of interest for people seeking to +run ownCloud on appliance hardware (i.e. NAS filers, routers, etc.). + + +Software Appliances +~~~~~~~~~~~~~~~~~~~ + +There are number of pre-made virtual machine-based appliances: + +- `SUSE Studio, ownCloud on openSuSE`_, runnable directly from an USB stick. +- `Ubuntu charm, ownCloud 4.5`_ +- `PCLinuxOS based appliance`_ +- `Fedora based appliance`_ + +ownCloud on Hardware Appliances +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +These are tutorials provided by the user communities of the respective appliances: + +- `QNAP Guide`_ for QNAP NAS appliances +- `OpenWrt Guide`_ for the popular embedded distribution for routers and NAS devices. + +.. todo:: Tutorials for running owncloud on Synology and Dreamplug. + +.. _OpenWrt Guide: http://wiki.openwrt.org/doc/howto/owncloud +.. _SUSE Studio, ownCloud on openSuSE: http://susestudio.com/a/TadMax/owncloud-in-a-box +.. _Ubuntu charm, ownCloud 4.5: http://jujucharms.com/charms/precise/owncloud +.. _PCLinuxOS based appliance: http://www.pclinuxos.com/forum/index.php/topic,100875.0.html +.. _Fedora based appliance: http://echorand.me/2012/02/26/owncloud-boxgrinder-pagekite-owncloud-appliance/ +.. _QNAP Guide: http://wiki.qnap.com/wiki/Category:OwnCloud diff --git a/admin_manual/installation_linux.rst b/admin_manual/installation_linux.rst new file mode 100644 index 000000000..ec870a370 --- /dev/null +++ b/admin_manual/installation_linux.rst @@ -0,0 +1,121 @@ +Linux Distributions +------------------- + +This section describes the installation process for different +distributions. If there are pre-made packages from ownCloud, +you are encouraged to prefer those over the vendor-provided +ones, since they usually are more up-to-date. + +Archlinux +~~~~~~~~~ + +There are two AUR packages for ownCloud: + +- `stable version`_ +- `development version`_ + +openSUSE +~~~~~~~~ + +.. note:: ready-to-use SLES and openSUSE RPM packages are available + in the openSUSE Build Service `ownCloud repository`_. + +1. Copy ownCloud to Apache's server directory : ``/srv/www/htdocs`` +2. Give the web server the necessary permissions: + ``sudo chown -R wwwrun owncloud`` + + - If you do not use "sudo" then you have to become root and + execute: ``chown -R wwwrun owncloud`` in the directory. + - (If you’re using mysql, you have to set the database character set + to something else then utf~8, for example latin1 otherwise some + keys will be to long for mysql) + +3. Open the folder in a browser and complete the setup wizard + +If have followed the steps above and want to try it out, run this +command in a terminal to start Apache if it’s not already running: + +1. ``sudo /etc/init.d/apache2 start`` +2. Go to ``http://servername/owncloud`` and walk through the setup. + +Fedora +~~~~~~ + +.. note:: ready-to-use RPM packages are available + in the openSUSE Build Service `ownCloud repository`_. + +Make sure SELinux is disabled or else the installation process will fail +with the following message: ``Config file (config/config.php) is not +writable for the webserver``. + +Configure Apache: + +1. If you already have a website running from Document Root but would + still like to install OwnCloud you can use a Name-based virtual host + entry and subdomain. +2. Edit your DNS record following this example: ``point owncloud.foo.com > + ip.ip.ip.ip`` + +.. todo:: + +CentOS 5 & 6 +~~~~~~~~~~~~ + +.. note:: ready-to-use CentOS RPM packages are available + in the openSUSE Build Service `ownCloud repository`_. + +1. Create a new file in ``/etc/httpd/conf/`` and call it ``owncloud.conf``. +2. You can use the following as an example: + +:: + + + Alias /owncloud /var/www/owncloud/ + + + Options None + Order allow,deny + allow from all + + + ServerAdmin foo@foofarm.com + DocumentRoot /var/www/html/owncloud + ServerName owncloud.foo.com + ErrorLog logs/owncloud.foo.info-error_log + CustomLog logs/owncloud.foo.info-access_log common + + + +3. Now edit your httpd.conf file which is usually located in + ``/etc/httpd/conf/httpd.conf`` +4. Add the following to the bottom: + ``Include /etc/httpd/conf/owncloud.conf`` +5. Restart apache and now when you point your browser to + ``owncloud.foo.com`` it should properly load without disturbing *foo.com* + +Gentoo +~~~~~~ + +Basically do everything like for a standard web server (see +above). Change permissions: ``chown -R apache:apache owncloud``\ +Allow .htaccess, modify ``/etc/apache2/vhosts.d/00_default_vhost.conf`` and +make sure this is in + +:: + + + Options Indexes FollowSymLinks MultiViews + AllowOverride All + Order allow,deny + allow from all + + +PCLinuxOS +~~~~~~~~~ + +Follow the Tutorial `ownCloud, installation and setup`_ on the PCLinuxOS web site. + +.. _stable version: http://aur.archlinux.org/packages.php?ID=47585 +.. _development version: http://aur.archlinux.org/packages.php?ID=38767 +.. _ownCloud repository: http://software.opensuse.org/search?q=owncloud&baseproject=ALL&lang=de +.. _ownCloud, installation and setup: http://pclinuxoshelp.com/index.php/Owncloud,_installation_and_setup diff --git a/admin_manual/installation_macos.rst b/admin_manual/installation_macos.rst new file mode 100644 index 000000000..1d02a352e --- /dev/null +++ b/admin_manual/installation_macos.rst @@ -0,0 +1,17 @@ +Mac OS X +-------- + +.. todo:: This section of the manual needs to be revised. + +This relies on `MAMP`_, which provides the required environment. + +1. Install MAMP and run it. +2. Go to ‘Preferences ? Apache’ and set ‘Document Root’ to + ``/Users//Sites``, so your Sites directory will be + used as Apache root. +3. Download ownCloud +4. Move it to ``~/Sites`` and extract it: + ``tar xfpj owncloud-4.5.tar.bz2`` +5. Now you can set it up by going to http://localhost:8888/owncloud + +.. _MAMP: http://www.mamp.info diff --git a/admin_manual/installation_source.rst b/admin_manual/installation_source.rst new file mode 100644 index 000000000..58c7fefba --- /dev/null +++ b/admin_manual/installation_source.rst @@ -0,0 +1,103 @@ +Manual Installation +------------------- + +If you do not want to use packages, here is how you setup ownCloud on from scratch +using a classic :abbr:`LAMP (Linux, Apache, MySQL, PHP)` setup: + +Prerequisites +~~~~~~~~~~~~~ + +To run ownCloud, your webserver must have the following installed: + +* php5 (>= 5.3) +* php5-json +* php-xml +* php-mbstring +* php5-zip +* php5-gd + +And as *optional* dependencies: + +* php5-sqlite (>= 3) +* curl +* libcurl3 +* libcurl3-dev +* php5-curl +* php5-intl +* php-pdo + +Commands for Ubuntu and Debian: + +:: + + apt-get install apache2 php5 php5-json php-xml php-mbstring php5-zip php5-gd + apt-get install php5-sqlite curl libcurl3 libcurl3-dev php5-curl php-pdo + +.. todo:: Document other distributions. + +You don’t need any WebDAV support of your webserver (i.e. apache’s mod_webdav) +to access your ownCloud data via WebDAV, ownCloud has a WebDAV server built in. + +Extract ownCloud and Copy to Your Webserver +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + tar -xjf path/to/downloaded/owncloud-x.x.x.tar.bz2 + cp -r owncloud /path/to/your/webserver + +Set the Directory Permissions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The owner of your webserver must own the apps/, data/ and config/ directories +in your ownCloud install. You can do this by running the following command for +the apps, data and config directories: + +:: + + chown -R www-data:www-data /path/to/your/owncloud/install/data + +Replace ``www-data:www-data`` with the user and group of the owner of your +webserver. + +.. note:: The ``data/`` directory will only be created after setup has run + (see below) and is not present by default in the tarballs. + +Enable .htaccess and mod_rewrite if Running Apache +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you are running the apache webserver, it is recommended that you enable +``.htaccess`` files as ownCloud uses them to enhance security and allows you to +use webfinger. To enable .htaccess files you need to ensure that +``AllowOverride`` is set to ``All`` in the ``Directory /var/www/`` section of +your virtual host file. This is usually in +``/etc/apache2/sites-enabled/000-default``. You should also run ``a2enmod +rewrite`` and ``a2enmod headers``. Then restart apache: service apache2 restart +(for Ubuntu systems). In order for the maximum upload size to be configurable, +the .htaccess file in the owncloud folder needs to be made writable by the +server. + +Follow the Install Wizard +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Open your web browser and navigate to your ownCloud instance. If you are +installing ownCloud on the same machine as you will access the install wizard +from, the url will be: http://localhost/ (or http://localhost/owncloud). For +basic installs we recommend SQLite as it is easy to setup (ownCloud will do it +for you). For larger installs you should use MySQL or PostgreSQL. Click on the +Advanced options to show the configuration options. You may enter admin +credentials and let ownCloud create its own database user, or enter a +preconfigured user. If you are not using apache as the webserver, please set +the data directory to a location outside of the document root. See the advanced +install settings. + +Test your Installation +~~~~~~~~~~~~~~~~~~~~~~ + +Login and start using ownCloud. Check your web servers errror log. If it shows +error, you might have missed a dependency or hit a bug with your particular +configuration. + +If you plan on using the Webfinger app and +your ownCloud installation is not in the webroot then you’ll have to manually +link ``/var/www/.well-known`` to ``/path/to/your/owncloud/.well-known``. diff --git a/admin_manual/installation_ucs.rst b/admin_manual/installation_ucs.rst new file mode 100644 index 000000000..37ab0a14a --- /dev/null +++ b/admin_manual/installation_ucs.rst @@ -0,0 +1,181 @@ +Univention Corporate Server +--------------------------- + +Subscribers to the ownCloud Enterprise edition can also integrate with +:abbr:`UCS (Univention Corporate Server)`. + +Prerequisites +~~~~~~~~~~~~~ + +The ownCloud integration relies on the MySQL database. Since "PostresSQL" +is more in a experimental state and "SQLite" is not very well suited for +multi-user installations, MySQL is the only way first of all. As of UCS +3.0 MySQL is not part of the maintained repository. Hence you you should +install it first and probably deactivate the unmaintained repository +eventually:: + + # ucr set repository/online/unmaintained="yes" + # univention-install mysql-server + # ucr set repository/online/unmaintained="no" + +.. note:: If MySQL is already installed and/or a password for the user root is + set, please make sure it is saved in /etc/mysql.secret, otherwise you + will experience problems. + +In case you want to install ownCloud from the repository, it is already enough +to enable the unmaintained repository for MySQL. You can skip the rest of this +section and read on at :ref:`Pre configuration`. ownCloud has further dependencies, +which all belong to the maintained repository. Install them as well:: + + # univention-install php5-mysql php5-ldap php5-gd + +The package manager is going to remove ``libgd2-noxpm``, which is not a problem +and nothing to worry about. + +Pre configuration +^^^^^^^^^^^^^^^^^ + +ownCloud makes use of the UCR, the Univention Configuration Registry. At +the moment, the values are being read during installation only. So you +might want to change them here, but you can do it later from within +ownCloud. For a later version we plan to provide an own ownCloud module +for the UMC (Univention Management Console). We think we found sane +defaults, nevertheless you might have your own requirements. The +installation script will listen to those UCR keys:In case you want to +override any default setting, simply add the key in question to the UCR +and assign your required value. + +.. tabularcolumns:: |l|p{5cm}|p{5cm}|l| +.. cssclass:: longtable +.. csv-table:: + :header: Key, Default, Description, Introduced + :widths: 20, 30, 30, 20 + + "owncloud/directory/data", "/var/lib/owncloud", "Specifies where the file storage will be placed", "2012.0.1" + "owncloud/db/name", "owncloud", "Name of the MySQL database. ownCloud will create an own user for it.", 2012.0.1 + "owncloud/user/quota", "(empty)", "The default quota, when a user is being added. Assign values in human readable strings, e.g. “2 GB”. Unlimited if empty.", 2012.0.1 + "owncloud/user/enabled", 0, "Wether a new user is allowed to use ownCloud by default.", 2012.0.1 + "owncloud/group/enabled", "0", "Wether a new group is allowed to be used in ownCloud by default.", 2012.4.0.4 + "owncloud/ldap/base/users", "cn=users,$ldap_base", "The users-subtree in the LDAP directory. If left blank it will fall back to the LDAP base.", 2012.4.0.4 + "owncloud/ldap/base/groups", "cn=groups,$ldap_base", "The groups-subtree in the LDAP directory. If left blank it will fall back to the LDAP base.", 2012.4.0.4 + "owncloud/ldap/groupMemberAssoc", "uniqueMember", "The LDAP attribute showing the group-member relationship. Possible values: uniqueMember, memberUid and member", 2012.4.0.4 + "owncloud/ldap/tls", 1, "Whether to talk to the LDAP server via TLS.", 2012.0.1 + "owncloud/ldap/loginFilter", "(&(|(&(objectClass=posixAccount) (objectClass=shadowAccount)) (objectClass=univentionMail) (objectClass=sambaSamAccount) (objectClass=simpleSecurityObject) (&(objectClass=person) (objectClass=organizationalPerson) (objectClass=inetOrgPerson))) (!(uidNumber=0)) (!(uid=*$)) (&(uid=%uid) (ownCloudEnabled=1)))", "The LDAP filter that shall be used when a user tries to log in.", 2012.0.1 + "owncloud/ldap/userlistFilter", "(&(|(&(objectClass=posixAccount) (objectClass=shadowAccount)) (objectClass=univentionMail) (objectClass=sambaSamAccount) (objectClass=simpleSecurityObject) (&(objectClass=person) (objectClass=organizationalPerson) (objectClass=inetOrgPerson))) (!(uidNumber=0))(!(uid=*$)) (&(ownCloudEnabled=1)))", "The LDAP filter that shall be used when the user list is being retrieved (e.g. for sharing)", 2012.0.1 + "owncloud/ldap/groupFilter", "(&(objectClass=posixGroup) (ownCloudEnabled=1))", "The LDAP filter that shall be used when the group list is being retrieved (e.g. for sharing)", 2012.4.0.4 + "owncloud/ldap/displayName", "uid", "The LDAP attribute that should be used as username in ownCloud", 2012.0.1 + "owncloud/ldap/group/displayName", "cn", "The LDAP attribute that should be used as groupname in ownCloud", 2012.4.0.4 + "owncloud/join/users/update", "yes", "Wether ownCloud LDAP schema should be applied to existing users", 2012.0.1 + "owncloud/group/enableDomainUsers", "1", "Wether the group “Domain Users” shall be enabled for ownCloud on install", 2012.4.0.4 + "owncloud/join/users/filter", "(&(|(&(objectClass=posixAccount) (objectClass=shadowAccount)) (objectClass=univentionMail) (objectClass=sambaSamAccount) (objectClass=simpleSecurityObject) (&(objectClass=person) (objectClass=organizationalPerson) (objectClass=inetOrgPerson))) (!(uidNumber=0)) (!(|(uid=*$) (uid=owncloudsystemuser) (uid=join-backup) (uid=join-slave))) (!(objectClass=ownCloudUser)))", "Filters, on which LDAP users the ownCloud schema should be applied to. The default excludes system users and already ownCloudUsers.", 2012.0.1 + "owncloud/join/groups/filter", "(empty)", "Filters which LDAP groups will be en/disabled for ownCloud when running the script /usr/share/owncloud/update-groups.sh", 2012.4.0.4 + + +If you want to override the default settings, simply create the key in +question in the UCR and assign your required value, for example +``ucr set owncloud/user/enabled=1`` or via UMC: + +.. image:: /images/ucsint2.png + + +Installation +^^^^^^^^^^^^ + +Now, we are ready to install ownCloud. This can be either done through the ownCloud UCS repository or by downloading the packages. + +Repository +"""""""""" + +To include the ownCloud UCS repository, you need to configure it using +the UCR. To do so, just use the following command: + +:: + + ucr set update/secure_apt="no" \ + repository/online/component/owncloud/description="ownCloud" \ + repository/online/component/owncloud/server=download.owncloud.com \ + repository/online/component/owncloud/prefix=ucs \ + repository/online/component/owncloud/defaultpackages=owncloud \ + repository/online/component/owncloud/version=current \ + repository/online/component/owncloud=enabled + +Subsequently, install the ownCloud package. It will auto-install +owncloud-schema as well. + +:: + + # univention-install owncloud + +If you want to make use of commercially unsupported packages, install +the unsupported package: + +:: + + # univention-install owncloud-unsupported + +Manually by download +"""""""""""""""""""" + +Download the integration packages (`from our website`_ or with wget as +below) and install them from within your download folder (note: the +package owncloud-unsupported is optional): + +:: + + # wget http://download.owncloud.com/download/ucs/owncloud_2012.0.1-0_all.deb + # wget http://download.owncloud.com/download/ucs/owncloud-schema_2012.0.3-0_all.deb + # wget http://download.owncloud.com/download/ucs/owncloud-unsupported_2012.0.3-0_all.deb + # dpkg -i owncloud*.deb + +ownCloud will be configured to fully work with LDAP. There is only one +local admin user “owncloudadmin”, you can find his password in +``/etc/owncloudadmin.secret``. Use this account, if you want to change basic +ownCloud settings. + +Postconfiguration (optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In the installation process a virtual host is set up (Apache is required +therefore). If you want to modify the settings, edit +``/etc/apache2/sites-available/owncloud`` and restart the web server. You +might want to do it to enable HTTPS connections.Besides that, you can +edit the ``.htaccess-File in /var/www/owncloud/``. In the latter file there +are also the PHP limits for file transfer specified. + +Using ownCloud +^^^^^^^^^^^^^^ + +If you decided to enable every user by default to use ownCloud, simply +open up ``http://myserver.com/owncloud/`` and log in with your LDAP +credentials and enjoy. + +If you did not, go to the UMC and enable the users who shall have access +(see picture below). Then, login at http://myserver.com/owncloud/ with +your LDAP credentials. + +.. image:: /images/ucsint1.png + +Updating users can also be done by the script +``/usr/share/owncloud/update-users.sh`` . It takes the following UCR variables +as parameters: ``owncloud/user/enabled`` for enabling or disabling, +``owncloud/user/quota`` as the Quota value and ``owncloud/join/users/filter`` as +LDAP filter to select the users to update. + +Groups 2012.4.0.4 +""""""""""""""""" + +Since ownCloud Enterprise 2012.4.0.4 group support is enabled. Groups, +that are activated for ownCloud usage, can be used to share files to +instead of single users, for example. It is also important to note, that +users can only share within groups where they belong to. Groups can be +enabled and disabled via UCM as shown in the screen shot below. + +.. image:: /images/ucsint.png + +Another way to enable or disable groups is to use the script +``/usr/share/owncloud/update-groups.sh``. Currently, it takes an argument +which can be 1=enable groups or 0=disable groups. The filter applied is +being taken from the UCR variable ``owncloud/join/groups/filter``. In case it is empty , a message will be displayed. + + +.. _from our website: https://owncloud.com/download diff --git a/admin_manual/installation_webservernotes.rst b/admin_manual/installation_webservernotes.rst new file mode 100644 index 000000000..d920c0bf2 --- /dev/null +++ b/admin_manual/installation_webservernotes.rst @@ -0,0 +1,156 @@ +Web server Notes +---------------- + +The most popular server choice for ownCloud is Apache, which is why +it is also the combinations tested best. However, it is also possible +to run ownCloud on other web servers. This section does not cover +Microsoft Internet Information Services (IIS), it is covered +in the `Windows 7 and Windows Server 2008`_ section. + +Nginx Configuration +~~~~~~~~~~~~~~~~~~~ + +- You need to insert the following code into + ``your nginx config file.`` +- Adjust ``server_name``, ``root``, ``ssl_certificate`` and + ``ssl_certificate_key`` to suit your needs. +- Make sure your SSL certificates are readable by the server (see + `http://wiki.nginx.org/HttpSslModule`_). + +:: + + # redirect http to https. + server { + listen 80; + server_name owncloud.example.org; + rewrite ^ https://$server_name$request_uri? permanent; # enforce https + } + + # owncloud (ssl/tls) + server { + listen 443 ssl; + ssl_certificate /etc/nginx/certs/server.crt; + ssl_certificate_key /etc/nginx/certs/server.key; + server_name owncloud.example.org; + root /path/to/owncloud; + index index.php; + client_max_body_size 1000M; # set maximum upload size + + # deny direct access + location ^ ^/(data|config|\.ht|db_structure\.xml|README) { + deny all; + } + + # default try order + location / { + try_files $uri $uri/ @webdav; + } + + # owncloud WebDAV + location @webdav { + fastcgi_split_path_info ^(.+\.php)(/.*)$; + fastcgi_pass 127.0.0.1:9000; # or use php-fpm with: "unix:/var/run/php-fpm/php-fpm.sock;" + fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; + fastcgi_param HTTPS on; + include fastcgi_params; + } + + # enable php + location ^ \.php$ { + fastcgi_pass 127.0.0.1:9000; # or use php-fpm with: "unix:/var/run/php-fpm/php-fpm.sock;" + fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; + fastcgi_param HTTPS on; + include fastcgi_params; + } + } + +.. note:: You can use Owncloud without SSL/TLS support, but we strongly + encourage you not to do that: + +- Remove the server block containing the redirect +- Change ``listen 443 ssl`` to ``listen 80;`` +- Remove ``ssl_certificate`` and ``ssl_certificate_key``. +- Remove ``fastcgi_params HTTPS on;`` + +.. note:: If you want to effectively increase maximum upload size you will also + have to modify your ``php-fpm configuration`` (``usually at + /etc/php5/fpm/php.ini``) and increase ``upload_max_filesize`` and + ``post_max_size`` values. You’ll need to restart php5-fpm and nginx + services in order these changes to be applied. + +Lighttpd Configuration +~~~~~~~~~~~~~~~~~~~~~~ + +This assumes that you are familiar with installing PHP application on +lighttpd. + +It is important to note that the ``.htaccess`` files used by ownCloud to protect +the ``data`` folder are ignored by lighttpd, so you have to secure it by yourself, +otherwise your ``owncloud.db``` database and user data are publicly readable even if +directory listing is off. You need to add two snippets to your lighttpd configuration +file: + +Disable access to data folder:: + + $HTTP["url"] =^ "^/owncloud/data/" { + url.access-deny = ("") + } + +Disable directory listing:: + + $HTTP["url"] =^ "^/owncloud($|/)" { + dir-listing.activate = "disable" + } + +Yaws Configuration +~~~~~~~~~~~~~~~~~~ + +This should be in your ``yaws_server.conf``. In the configuration file, the +``dir_listings = false`` is important and also the redirect from ``/data`` +to somewhere else, because files will be saved in this directory and it +should not be accessible from the outside. A configuration file would look +like this:: + + + port = 80 + listen = 0.0.0.0 + docroot = /var/www/owncloud/src + allowed_scripts = php + php_handler = + errormod_404 = yaws_404_to_index_php + access_log = false + dir_listings = false + + /data == / + + + +The apache ``.htaccess`` file that comes with ownCloud is configured to +redirect requests to nonexistent pages. To emulate that behaviour, you +need a custom error handler for yaws. See this `github gist for further +instructions`_ on how to create and compile that error handler. + +Hiawatha Configuration +~~~~~~~~~~~~~~~~~~~~~~ + +Add ``WebDAVapp = yes`` to the ownCloud virtual host. Users accessing +WebDAV from MacOS will also need to add ``AllowDotFiles = yes``. + +Disable access to data folder:: + + UrlToolkit { + ToolkitID = denyData + Match ^/data DenyAccess + } + + +PageKite Configuration +~~~~~~~~~~~~~~~~~~~~~~ + +You can use this `PageKite how to`_ to make your local ownCloud accessible from the +internet using PageKite. + +.. _github gist for further instructions: https://gist.github.com/2200407 +.. _PageKite how to: https://pagekite.net/wiki/Howto/GNULinux/OwnCloud/ + +.. _`http://wiki.nginx.org/HttpSslModule`: http://wiki.nginx.org/HttpSslModule diff --git a/admin_manual/installation_windows.rst b/admin_manual/installation_windows.rst new file mode 100644 index 000000000..6f636939a --- /dev/null +++ b/admin_manual/installation_windows.rst @@ -0,0 +1,294 @@ +Windows 7 and Windows Server 2008 +--------------------------------- + +.. note:: You must move the data directory outside of your public root. + (See advanced install settings) + +This section describes how to install ownCloud on Windows with :abbr:`IIS +(Internet Information Services)`. + +It assumes that you have a vanilla, non-IIS enabled Windows +machine – Windows 7 or Server 2008. After enabling IIS, the steps are +essentially identical for Windows 7 and Windows Server 2008. + +For installation, physical access or a remote desktop connection is required. +You should leverage MySQL as the back end database for ownCloud. +If you do not want to use MySQL, it is possible to use Postgres or SQLite +instead. Microsoft SQL Server is not yet support. + +Enabling SSL is not yet covered by this section. + +.. note:: If you make your desktop machine or server available + outside your LAN, you must maintain it. Monitor the logs, manage + the access, apply patches to avoid compromising the system at large. + +There are 4 primary steps to the installation, and then a 5th step +required for configuring everything to allow files larger than the +default 2MB. + +1. Install IIS with CGI support – enable IIS on your Windows machine. + +2. Install PHP – Grab, download and install PHP. + +3. Install MySQL – Setup the MySQL server manager and enable ownCloud to create + an instance. + +4. Install ownCloud – The whole reason we are here! + +5. Configure upload sizes and timeouts to enable large file uploads – So that you + can upload larger files. + +Activate IIS with CGI Support +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Windows 7 +^^^^^^^^^ + +1. Go to :guilabel:`Start --> Control Panel --> Programs`. + +2. Under Programs and Features, there is link titled :guilabel:`Turn Windows Features on + and Off`. Click on it. + +3. There is a box labeled Internet Information Services, expand it. + +4. Expand World Wide Web Services and all the folders underneath. + +5. Select the folders as illustrated in the picture below to get your IIS + server up and running. + +.. figure:: images/win7features.jpg + :width: 250px + :align: center + :alt: Windows features required for ownCloud on Windows 7 + :figclass: align-center + + Windows Features required for ownCloud on Windows 7 + +You do not need an FTP server running, so you should tune +that feature off for your server. You definitely need the IIS Management +Console, as that is the easiest way to start, stop, restart you server, +as well as where you change certificate options and manage items like +file upload size. You must check the CGI box under Application +Development Features, because CGI is how you enable PHP on IIS. + +You have to turn off WebDAV publishing or the Windows WebDAV +conflicts with the ownCloud WebDAV interface. This might already be +turned off for you, just make sure it stays that way. The common HTTP +features are the features you would expect from a web server. +With the selections on this page, IIS will now serve up a web page for you. + +Restart IIS by going to the IIS manager (:guilabel:`Start --> IIS Manager`). +Select your website, and on the far right side is a section titled +:guilabel:`Manage Server`. Make sure that the service is started, or click +:guilabel:`Start` to start the services selected. Once this is complete, you +should be able to go to a web browser and navigate to `http://localhost``. + +This should open the standard IIS 7 splash page, which is just a static image +that says your web server is running. Assuming you were able to get the +splash page, it is safe to say your web server is now up and running. + + +Windows Server 2008 +^^^^^^^^^^^^^^^^^^^ + +1. Go to :guilabel:`Start --> Control Panel --> Programs`. + +2. Under Programs and Features, there is link titled + :guilabel:`Turn Windows Features on and Off`. Click on it. + +3. This will bring up the Server Manager. + +4. In the server manager, Click on Roles, and then click Add Roles. + +5. Use the :guilabel:`Add Roles Wizard` to add the web server role. + +.. figure:: images/winserverroles.jpg + :width: 300px + :align: center + :alt: server roles required for owncloud + :figclass: align-center + + Server roles required for ownCloud + +6. Make sure that, at a minimum, the same boxes are checked in this wizard that + are checked in the Windows 7 Section. For example, make sure that the CGI + box is checked under Application Development Features, and that WebDAV + Publishing is turned off. With Remote Desktop Sharing turned on, the + detailed role service list looks like the figure “Role Services”. + +7. Restart IIS by going to the IIS manager (:guilabel:`Start --> IIS Manager`). + +8. Select your website, and on the far right side is a section titled Manage + Server. Make sure that the service is started, or click “Start” to start the + services selected. + +9. Once this is complete, you should be able to go to a web browser and type + "localhost". This should open the standard IIS 7 splash page, which is just + a static image that says your web server is running.Assuming you were able + to get the splash page, it is safe to say your web server is now up and + running. The next part of this “how to” installs PHP on the server. + +Installing PHP +~~~~~~~~~~~~~~ + +This part is also straightforward, but it is necessary to remind you that this +is for IIS only. + +1. Go to the following link and grab the PHP installer for version "VC9 Non + Thread Safe" 32 or 64 bit based on your system. + http://windows.php.net/download/ + +.. note:: If you are using Apache, make sure you grab VC6 instead, lower on the + page. + +2. Once through that login, select the location that is closest to you + geographically. + +3. Run that install wizard once it is downloaded. Read the license agreement, + agree, select an install directory. + +4. Then select IIS FastCGI as the install server. + +5. Take the default selections for the items to install, and click next. Then + click install. + +6. And, after a few minutes, PHP will be installed. On to MySQL. + +Installing MySQL +~~~~~~~~~~~~~~~~ + +This part installs MySQL on your Windows machine. + +1. Point your browser to http://dev.mysql.com/downloads/ and download the + latest community edition for your OS – the 32 or 64 bit version. Please + download the ``MSI Installer`` as it will make life easier. + +2. Once downloaded, install MySQL (5.5 at the time of writing). Select the + Typical installation. + +3. When that finishes, check the box to launch the MySQL Instance Configuration + Wizard and click Finish. + +4. Select a standard configuration, as this will be the only version of MySQL + on this machine. + +5. Select to install as a windows service, and Check the Launch the MySQL + Server Automatically button. + +6. Select the modify security settings box on the next page, and enter a + password you will remember. You will need this password when you configure + ownCloud. + +7. Uncheck ``enable`` root access from remote machines” for security reasons. + +8. Click execute, and wait while the instance is created and launched. + +9. Click Finish when this is all complete. + +.. You can make some pretty good educated guesses on the type of install needed + for ownCloud. %% That's not really useful, clarify! + +Take particular note of your MySQL password, as the user name ``root`` +and the password you select will be necessary alter on in the ownCloud +installation. As an aside, this link is an excellent resource for questions on +how to configure your MySQL instance, and also to configure PHP to work with +MySQL. This, however, is not strictly necessary as much of this is handled when +you download ownCloud. + +More information in this topic can be found in a `tutorial on the IIS web site`_. + +.. _tutorial on the IIS web site: + http://learn.iis.net/page.aspx/353/install-and-configure-mysql-for-php-applications-on-iis-7-and-above/ + +Installing ownCloud +~~~~~~~~~~~~~~~~~~~ + +1. Download the latest version of ownCloud from http://owncloud.org/download. + +2. It will arrive as a tar.bz2 file, and I recommend something like jZip for a + free utility to unzip it. + +3. Once you have the ownCloud directory unzipped and saved locally, copy it + into your wwwroot directory (probably ``c:\inetpub\wwwroot``). + +.. note:: You cannot install directly into the directory ``wwwroot`` from jzip, + as only the administrator can unzip into the ``wwwroot`` directory. If you save + it in a different folder, and then move the files into ``wwwroot`` in Windows + explorer, it works. This will install ownCloud locally in your root web + directory. You can use a subdirectory called owncloud, or whatever you want – + the www root, or something else. + +4. It is now time to give write access to the ownCloud directory to the + ownCloud server: Navigate your windows explorer over to + ``inetpub/wwwroot/owncloud`` (or your installation directory if you selected + something different). + +5. Right click and select properties. Click on the security tab, and click the + button “to change permissions, click edit”. + +6. Select the “users” user from the list, and check the box “write”. + +7. Apply these settings and close out. + +8. Now open your browser and go to ``http://localhost/owncloud`` (or localhost + if it is installed in the root www directory). This should bring up the + ownCloud configuration page. + +9. At this page, you enter your desired ownCloud user name and password for the + administrator, and expand the little arrow. + +10. Select MySQL as the database, and enter your MySQL database user name, + password and desired instance name – use the user name and password you + setup for MySQL earlier in step 3, and pick any name for the database + instance. + +.. note:: The owncloud admin password and the MySQL password CANNOT be the same + in any way. + +11. Click next, and ownCloud should have you logged in as the admin user, and + you can get started exploring ownCloud, creating other users and more! + +Configuring ownCloud, PHP and IIS for Large File Uploads +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Before going too nuts on ownCloud, it is important to do a couple of +configuration changes to make this a useful service for you. You will probably +want to increase the ``max upload size``, for example. The default upload is +set to ``2MB``, which is too small for even most MP3 files. + +To do that, simply go into your ``PHP.ini`` file, which can be found in your +``C:\Program Files (x86)\PHP`` folder. In here, you will find a ``PHP.ini``` +file. Open this in a text editor, and look for a few key attributes to +change: + ++ ``upload_max_filesize`` – change this to something good, like 1G, and you + will get to upload much larger files. + ++ ``post_max_size`` – also change this size, and make it larger than the max + upload size you chose, like 1G. + +There are other changes you can make, such as the timeout duration for +uploads, but for now you should be all set in the ``PHP.ini`` file. + +Now you have to go back to IIS manager and make one last change to enable file +uploads on the web server larger than 30MB. + +1. Go to the start menu, and type ``iis manager``. + +2. Open IIS Manager Select the website you want enable to accept large file + uploads. + +3. In the main window in the middle double click on the icon ``Request + filtering``. + +4. Once the window is opened you will see a bunch of tabs across the top of the + far right, + + Select :guilabel:`Edit Feature Settings` and modify the :guilabel:`Maximum + allowed content length (bytes)` + +5. In here, you can change this to up to 4.1 GB. + +.. note:: This entry is in BYTES, not KB. + +You should now have ownCloud configured and ready for use. diff --git a/developer_manual/apps.rst b/developer_manual/apps.rst index 9b8dd511e..336b82243 100644 --- a/developer_manual/apps.rst +++ b/developer_manual/apps.rst @@ -9,6 +9,9 @@ type doesn't have to be specified if the app doesn't match any of them. Currently supported "types": +**prelogin** +apps which needs to load on the login page + **filesystem** apps which provides filesystem functionality (e.g. files sharing app) diff --git a/user_manual/connecting/index.rst b/user_manual/connecting_browser.rst similarity index 100% rename from user_manual/connecting/index.rst rename to user_manual/connecting_browser.rst diff --git a/user_manual/connecting/webdav.rst b/user_manual/connecting_webdav.rst similarity index 93% rename from user_manual/connecting/webdav.rst rename to user_manual/connecting_webdav.rst index f484f7efb..c2d015304 100644 --- a/user_manual/connecting/webdav.rst +++ b/user_manual/connecting_webdav.rst @@ -2,27 +2,27 @@ Mounting ownCloud via WebDAV ============================= All major operating systems allow for mounting a users ownCloud via WebDAV, -a HTTP extension as specified in :rfc:`2518`. This chapter describes how to +a HTTP extension as specified in :rfc:`2518`. This chapter describes how to setup WebDAV on different operating systems. Windows ------- -On Windows, you can assign ownCloud a drive letter. This allows you to -browse files stored on an ownCloudserver the way you would files stored in a -mapped network drive. +On Windows, you can assign ownCloud a drive letter. This allows you to +browse files stored on an ownCloudserver the way you would files stored in a +mapped network drive. Using this feature requires network connectivity. If you want to store your files offline, use the ownCloud Client to sync all files on your -ownCloud to one or more directories of your local hard drive. +ownCloud to one or more directories of your local hard drive. -.. note:: Prior to mapping your drive, you will need to permit the use of +.. note:: Prior to mapping your drive, you will need to permit the use of Basic Authentication in the Windows Registry. The procedure is documented in KB841215_ and differs between Windows XP/Server 2003 and Windows Vista/7. Please follow the Knowledge Base article - before proceeding, and follow the Vista instructions if you run - Windows 7. + before proceeding, and follow the Vista instructions if you run + Windows 7. Mapping via the command line ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -34,7 +34,7 @@ Running net use Z: https://www.yourserver.com/owncloud/remote.php/webdav /user:youruser yourpassword will map the files of your ownCloud account to the drive letter Z:. An alternative -syntax is: +syntax is: net use Z: \\www.yourserver.com@ssl\owncloud\remote.php\webdav /user:youruser yourpassword @@ -48,24 +48,24 @@ Use either of the following syntaxes:: Please note that this allows anyone to sniff your ownCloud data with ease, especially on public WiFi hotspots. Plain HTTP should therefore only be used in conjunction -with a VPN tunnel when used on Laptops. +with a VPN tunnel when used on Laptops. Using Windows Explorer ~~~~~~~~~~~~~~~~~~~~~~ Right-click on ``Computer`` entry and select ``Map network drive...``. Choose a local network drive to map ownCloud to. Finally, enter the address to your ownCloud instance, followed by -``/remote.php/webdav``, e.g. :: +``/remote.php/webdav``, e.g. :: https://www.yourserver.com/owncloud/remote.php/webdav -for an SSL protected server. Check ``Reconnect at logon`` to make this mapping persistent +for an SSL protected server. Check ``Reconnect at logon`` to make this mapping persistent across reboots. If you want to connect as another user, check ``Connect using different credentials``. -.. figure:: images/explorer_webdav.png +.. figure:: images/explorer_webdav.png :scale: 80% - - Mapping WebDAV on Windows Explorer. + + Mapping WebDAV on Windows Explorer. After pressing ``Finish``, Windows Explorer will map the network drive and your ownCloud instance should be available @@ -83,7 +83,7 @@ The port depends on whether your ownCloud server supports SSL or not. Cyberduck Port 80 (for WebDAV) 443 (for WebDAV (HTTPS/SSL)) - + Use the 'More Options' drop-down menu to add the rest of your webdav URL into the 'Path' field. e.g.: Path @@ -101,7 +101,7 @@ Solution encrypted connections. If you encounter an error mounting an SSL-encrypted ownCloud instance, please contact your provider about assigning a dedicated IP address for your SSL-based server. - + Problem I receive the error ``Error 0x800700DF: The file size exceeds the limit allowed and cannot be saved.`` @@ -112,10 +112,10 @@ Solution by clicking on ``Modify``. In order to increase the limit to the maximum value of 4GB, pick ``Decimal`` and enter ``4294967295`` as value. Afterwards, reboot Windows or restart the ``WebClient`` service. - + .. todo:: - document registry keys on file size limit and not complaining in no network cases + document registry keys on file size limit and not complaining in no network cases Mac OS X -------- @@ -126,7 +126,7 @@ In the Finder, choose ``Go > Connect to Server,`` type the address of the server ``Server Address`` field, and click ``Connect``. The server address should be in a form similar to this: ``ADDRESS/files/webdav.php``. For our example, it would be:: - https://www.yourserver.com/owncloud/files/webdav.php + https://www.yourserver.com/owncloud/files/webdav.php For details, check the respective `vendor documentation`_ at the Apple website. @@ -155,8 +155,8 @@ Assuming your owncloud instance is installed at ``http://www.yourserver.com/ownc Ubuntu/Gnome (Nautilus) ~~~~~~~~~~~~~~~~~~~~~~~ -.. figure:: images/nautilus_webdav.png - +.. figure:: images/nautilus_webdav.png + Nautilus WebDAV mounting dialog Mounting from command line diff --git a/user_manual/contacts.rst b/user_manual/contacts.rst index 019de2da3..cf1f9c676 100644 --- a/user_manual/contacts.rst +++ b/user_manual/contacts.rst @@ -16,10 +16,10 @@ Importing ~~~~~~~~~ So first well check out how to import all the VCF files as they are a lot -more faster way of creating contacts in this wonderful app. +more faster way of creating contacts. Just below the contact list, 3 buttons: The middle one let you upload files. -.. figure:: images/contact_bottombar.jpg +.. image:: images/contact_bottombar.jpg Once you've clicked it, the upload window let you choose your files. @@ -27,17 +27,17 @@ We can upload the files one by one or upload all of them at one go. Let me demonstrate. Open the directory in which you store all the files and then do the following -Keep pressing ctrl and select the files to upload. +Keep pressing CTRL and select the files to upload. After you are done just click on the open button After the upload it should look something like this in which all the names and contacts will be sorted alphabetically -.. figure:: images/contact_vcfpick.jpg +.. image:: images/contact_vcfpick.jpg Then, the interface ask you where to put your imported contacts. You have the ability to choose an existing addressbook or to create a new one. -Then click on "Ok" and that's all for the import of contacts. +Then click on "OK" and that's all for the import of contacts. -.. figure:: images/contact_import.jpg +.. image:: images/contact_import.jpg Create contacts manually ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -50,7 +50,7 @@ the name, the address, the e-mail, the telephone nr, ... Just click on a field and start typing the information. You can use the "Add Field" button to add another types of information for this contact. -.. figure:: images/contact_emptycontact.jpg +.. image:: images/contact_emptycontact.jpg When you want to remove an information of your contact, just click on little delete icon at the right of the field you want to remove. @@ -61,7 +61,7 @@ Adding picture to the contact There are two methods in which you can give a picture id to the specific contact -.. figure:: images/contact_picture.jpg +.. image:: images/contact_picture.jpg 1) **Direct upload** 2) **Select pics already uploaded in ownCloud files.** @@ -69,7 +69,7 @@ There are two methods in which you can give a picture id to the specific contact After you have selected the picture for the contact you get an option to crop the picture to suit your requirements -.. figure:: images/contact_crop.jpg +.. image:: images/contact_crop.jpg You can crop the picture however you wish and then press OK. @@ -85,7 +85,7 @@ When you click on the third button of the bottom bar, you will have access to the application's settings. Then, press on the "More button" to access the options of your Addressbooks. -.. figure:: images/contact_del_ab.jpg +.. image:: images/contact_del_ab.jpg You have there the ability to add, delete, download or share your addressbooks. Hover your cursor on every icon to see what they mean. @@ -105,7 +105,7 @@ Syncing with Android 4) After the app has checked your login details you may just select- Sync server to phone option 5) That's it there is nothing else to do for Android :) -.. figure:: images/contact_syncopt.jpg +.. image:: images/contact_syncopt.jpg Syncing your IOS device ~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/user_manual/files.rst b/user_manual/files.rst new file mode 100644 index 000000000..0c59546a6 --- /dev/null +++ b/user_manual/files.rst @@ -0,0 +1,52 @@ +Accessing your Files +==================== + + +Desktop +------- + +Your ownCloud instance can be accessed on every platform via the web interface. There are also options to integrate it with your desktop: + +In most cases, accessing ownCloud using your file manager will be +sufficient: + +- *Connect to Server...* `in your file manager`_: + ``webdav://ADDRESS/files/webdav.php`` + +- Change the protocol to ``dav://`` in Nautilus or ``http://`` in + Finder + +However, some applications only allow you to save to a local folder. To +get around this issue, you can: + ++ `Sync your ownCloud folders and local folders`_ + ++ `Mount ownCloud to a local folder without sync`_ + +The +Desktop Syncing Client called Mirall is now released for Linux and +Windows. You can follow the current changes at the `ownCloud Mirall +repository`_. We work on porting this to Mac OS and packaging for all +major linux distributions. + +Mobile +------- + +There are apps in development for both `Android`_ and `webOS`_. Feel +free to `contribute, if you can`_! Right now you can use other apps to +connect to ownCloud from your phone via WebDAV. `WebDAV Navigator`_ is a +good (proprietary) app for `Android App`_ , `iPhone`_ & `BlackBerry`_. + + + +.. _in your file manager: http://en.wikipedia.org/wiki/Webdav#Implementations +.. _Sync your ownCloud folders and local folders: http://owncloud.org/documentation/sync-clients/ +.. _Mount ownCloud to a local folder without sync: http://owncloud.org/use/webdav/ +.. _ownCloud Mirall repository: https://gitorious.org/owncloud/mirall +.. _Android: http://gitorious.org/owncloud/android +.. _webOS: http://gitorious.org/owncloud/webos +.. _contribute, if you can: /contribute/ +.. _WebDAV Navigator: http://seanashton.net/webdav/ +.. _Android App: http://market.android.com/details?id=com.schimera.webdavnavlite +.. _iPhone: http://itunes.apple.com/app/webdav-navigator/id382551345 +.. _BlackBerry: http://appworld.blackberry.com/webstore/content/46279 diff --git a/user_manual/images/calender.png b/user_manual/images/calender.png new file mode 100644 index 000000000..720c86c59 Binary files /dev/null and b/user_manual/images/calender.png differ diff --git a/user_manual/images/calender1.png b/user_manual/images/calender1.png new file mode 100644 index 000000000..2ae85a0e0 Binary files /dev/null and b/user_manual/images/calender1.png differ diff --git a/user_manual/images/calender2.png b/user_manual/images/calender2.png new file mode 100644 index 000000000..b0b6568c9 Binary files /dev/null and b/user_manual/images/calender2.png differ diff --git a/user_manual/images/calender3.png b/user_manual/images/calender3.png new file mode 100644 index 000000000..b321fa369 Binary files /dev/null and b/user_manual/images/calender3.png differ diff --git a/user_manual/images/calender4.png b/user_manual/images/calender4.png new file mode 100644 index 000000000..acc00e5a8 Binary files /dev/null and b/user_manual/images/calender4.png differ diff --git a/user_manual/images/calender5.png b/user_manual/images/calender5.png new file mode 100644 index 000000000..8d1133287 Binary files /dev/null and b/user_manual/images/calender5.png differ diff --git a/user_manual/connecting/images/explorer_webdav.png b/user_manual/images/explorer_webdav.png similarity index 100% rename from user_manual/connecting/images/explorer_webdav.png rename to user_manual/images/explorer_webdav.png diff --git a/user_manual/images/kdes.png b/user_manual/images/kdes.png new file mode 100644 index 000000000..1d231c9af Binary files /dev/null and b/user_manual/images/kdes.png differ diff --git a/user_manual/images/kdes1.png b/user_manual/images/kdes1.png new file mode 100644 index 000000000..8a9f12d0b Binary files /dev/null and b/user_manual/images/kdes1.png differ diff --git a/user_manual/images/kdes2.png b/user_manual/images/kdes2.png new file mode 100644 index 000000000..62a85011d Binary files /dev/null and b/user_manual/images/kdes2.png differ diff --git a/user_manual/images/kdes3.png b/user_manual/images/kdes3.png new file mode 100644 index 000000000..9c3b0985a Binary files /dev/null and b/user_manual/images/kdes3.png differ diff --git a/user_manual/images/kdes4.png b/user_manual/images/kdes4.png new file mode 100644 index 000000000..6b82a89e9 Binary files /dev/null and b/user_manual/images/kdes4.png differ diff --git a/user_manual/images/kdes5.png b/user_manual/images/kdes5.png new file mode 100644 index 000000000..9ef780ce7 Binary files /dev/null and b/user_manual/images/kdes5.png differ diff --git a/user_manual/images/kdes6.png b/user_manual/images/kdes6.png new file mode 100644 index 000000000..fd2420624 Binary files /dev/null and b/user_manual/images/kdes6.png differ diff --git a/user_manual/images/kdes7.png b/user_manual/images/kdes7.png new file mode 100644 index 000000000..5393cb9d3 Binary files /dev/null and b/user_manual/images/kdes7.png differ diff --git a/user_manual/images/kdes9.png b/user_manual/images/kdes9.png new file mode 100644 index 000000000..e885d20cd Binary files /dev/null and b/user_manual/images/kdes9.png differ diff --git a/user_manual/images/mediaplayer.png b/user_manual/images/mediaplayer.png new file mode 100644 index 000000000..6e7f5615c Binary files /dev/null and b/user_manual/images/mediaplayer.png differ diff --git a/user_manual/connecting/images/nautilus_webdav.png b/user_manual/images/nautilus_webdav.png similarity index 100% rename from user_manual/connecting/images/nautilus_webdav.png rename to user_manual/images/nautilus_webdav.png diff --git a/user_manual/index.rst b/user_manual/index.rst index e62860939..2eaf82a38 100644 --- a/user_manual/index.rst +++ b/user_manual/index.rst @@ -7,10 +7,17 @@ Contents :maxdepth: 2 introduction - connecting/index - connecting/webdav + connecting_browser + connecting_webdav + files contacts bookmarks + sync + sync_kde + sync_osx + sync_ios + mediaplayer + versioncontrol .. add more chapters diff --git a/user_manual/mediaplayer.rst b/user_manual/mediaplayer.rst new file mode 100644 index 000000000..eebf8e866 --- /dev/null +++ b/user_manual/mediaplayer.rst @@ -0,0 +1,27 @@ +Native Media Player Support +=========================== + +.. image:: images/mediaplayer.png + +You can access your music stored in ownCloud with every +Ampache-compatible media player. You can find the URL for your specific +ownCloud installation in your personal settings, or replace ADDRESS with +the URL of your ownCloud installation yourself. + +``Ampache-URL: http://ADDRESS/apps/media/`` + +Ampache-compatible players that work with ownCloud include: + +- `amaroK`_, standard KDE music player +- `tomahawk`_, cross platform player +- `justplayer`_, music player for android + +You can find more information about Ampache and other players at the +`Ampache wikipedia article`_ + +The current maintainer of the Media Player is Robin Appelman. + +.. _amaroK: http://amarok.kde.org/ +.. _tomahawk: http://www.tomahawk-player.org/ +.. _justplayer: http://justplayer-dev.blogspot.com/ +.. _Ampache wikipedia article: http://en.wikipedia.org/wiki/Ampache diff --git a/user_manual/sync.rst b/user_manual/sync.rst new file mode 100644 index 000000000..4cafd1541 --- /dev/null +++ b/user_manual/sync.rst @@ -0,0 +1,14 @@ +Desktop Synchronisation +======================== + +For synchronizing files with your desktop computer, we recommend using the +`ownCloud Client`_ for Windows, Mac OS X and Linux. Its usage is documented +separately in the `ownCloud Desktop Client Manual`_. + +Furthermore, It is possible to synchronize your ownCloud calendar and address book +with a variety of different operating systems and devices. It is also possible to +mount your ownCloud storage via WebDAV, which is also documented in the next chapters. + + +.. _ownCloud Client: http://owncloud.org/sync-client/ +.. _ownCloud Desktop Client Manual: http://doc.owncloud.com/desktop/1.1/ diff --git a/user_manual/sync_ios.rst b/user_manual/sync_ios.rst new file mode 100644 index 000000000..b488bd899 --- /dev/null +++ b/user_manual/sync_ios.rst @@ -0,0 +1,59 @@ +iOS - Synchronize iPhone/iPad +============================= + + + + +Synchronizing the Calendar +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +#. Open the settings application. +#. Select Mail, Contacts, Calendars. +#. Select Add Account. +#. Select Other as account type. +#. Select Add CalDAV account. +#. For server, type ``ADDRESS/remote.php/caldav/principals/username`` +#. Enter your user name and password. +#. Select Next. +#. If your server does not support SSL, a warning will be displayed. + Select Continue. +#. If the iPhone is unable to verify the account information perform the + following: + + - Select OK. + - Select advanced settings. + - Make sure Use SSL is set to OFF. + - Change port to 80. + - Go back to account information and hit Save. + +Your calendar should now be visible in the Calendar application + +Synchronizing the Address book +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +#. Open the settings application. +#. Select Mail, Contacts, Calendars. +#. Select Add Account. +#. Select Other as account type. +#. Select Add CardDAV account. +#. For server, type ``ADDRESS/remote.php/carddav/principals/username`` +#. Enter your user name and password. +#. Select Next. +#. If your server does not support SSL, a warning will be displayed. + Select Continue. +#. If the iPhone is unable to verify the account information perform the + following: + + - Select OK. + - Select advanced settings. + - Make sure Use SSL is set to OFF. + - Change port to 80. + - Go back to account information and hit Save. + +Now should now find your contacts in the address book of your +iPhone.Problems have been reported for iOS 4.X. A possible solution is +at the `forum`_. + + + +.. _forum: http://forum.owncloud.org/viewtopic.php?f=3&t=71&p=2211#p2197 diff --git a/user_manual/sync_kde.rst b/user_manual/sync_kde.rst new file mode 100644 index 000000000..6e7a1a67d --- /dev/null +++ b/user_manual/sync_kde.rst @@ -0,0 +1,57 @@ +Synchronizing with KDE SC +========================= + + + +.. image:: /images/kdes1.png + +From KDE SC 4.8 and forward setting up ownCloud is very easy.From System +Settings Personal Information/Akonadi Resources Configuration select DAV +Groupware resource. + + +.. image:: /images/kdes2.png + +Enter your ownCloud username and password and click "Next". + + +.. image:: /images/kdes3.png + +Select ownCloud in the drop down list and click "Next". + + + +.. image:: /images/kdes4.png + +Enter the host name and installation path. If you do not use SSL +remember to de-select "Use secure connection". + + +.. image:: /images/kdes5.png + +Test the connection. If everything went well you should see a message +like the one below. + + +.. image:: /images/kdes6.png + +Click "Finish" and you will be able to change the display name and +refresh interval. + + +.. image:: /images/kdes7.png + +Now you should see the Akonadi resource doing the first +synchronization. + + +.. image:: /images/kdes8.png + +You can find the Contacts and Calendars in Kontact (or +KOrganizer/KAddressbook if you run the programs separately.) + + +.. image:: /images/kdes9.png + +.. image:: /images/kdes.png + diff --git a/user_manual/sync_osx.rst b/user_manual/sync_osx.rst new file mode 100644 index 000000000..b45a1cbe1 --- /dev/null +++ b/user_manual/sync_osx.rst @@ -0,0 +1,50 @@ +Synchronizing with OS X +======================= + +To use ownCloud with iCal you will need to use the following URL: + + http://ADDRESS/remote.php/caldav/principals/username/ + +In principle the setup is the same as with iOS using the path +``ADDRESS/remote.php/caldav/principals/username/`` to sync with +ownCloud. For OS X 10.7 Lion and 10.8 Mountain Lion everything works +fine, but OS X 10.6 (Snow Leopard) and older needs some fiddling to +work. A user contributed the following: + +#. Make sure, Addressbook is not running. If it is, select the windows + and press Command + Q to terminate it. +#. Navigate to ``/Users/YOUR\_USERNAME/Library/Application + Support/AddressBook/Sources``. If you have all ready some kind of + address book setup, it is likely you will see some folders named like + this ``BEA92826-FBF3-4E53-B5C6-ED7C2B454430``. Note down what folders + there are now and leave the window open. +#. Open addressbook and try to add a new CardDav addressbook. At this + point, it does not matter what information you enter. It will come up + with the same error message you mentioned before when you click + "Create". Ignore it and click "Create" again. A non-functional + address book will be added. +#. Close Address-Book again using Command + Q +#. Go back to the folder window from step 2. You will now see a newly + created folder with another long string as its name. +#. Navigate to the newly created folder and edit the + ``Configuration.plist`` with your favorite text editor. +#. Search for a section looking like this: + + ``servername http://:0(null) username Whatever_you_entered_before`` + +8. Make it look like this. Please note the :80 after **YOUR_DOMAIN** + it is important: + + + ``servernamehttp://YOUR_DOMAIN:80/owncloud/remote.php/carddav/principals/username usernameusername`` + +9. Save the file and open Address Book again. It will not work yet. + +10. Open the preferences for your ownCloud CardDAV-Account and enter your password. + +11. You may have to restart Address Book once more. After this, it should work. + +There is also an easy `HOWTO`_ in the forum. + + +.. _HOWTO: http://forum.owncloud.org/viewtopic.php?f=3&t=132 diff --git a/user_manual/versioncontrol.rst b/user_manual/versioncontrol.rst new file mode 100644 index 000000000..e5d82fe7e --- /dev/null +++ b/user_manual/versioncontrol.rst @@ -0,0 +1,10 @@ +Version Control +=============== + + +ownCloud supports simple version control for files. Versioning is +enabled by default, and creates backups of files which are accessible +via the history tab. This tab also links to the history page, where you +can roll back a file to any previous version.Changes made at intervals +greater than two minutes are saved in data/[user]/versions, and made +accessible using the above pages.