MarkLogic 9 Product Documentation

Administrator's Guide — Chapter 9

Accesses a Database for Read and Write, Not XQuery Execution

In MarkLogic Server, WebDAV servers are defined at the group level and apply to all hosts within the group. Each WebDAV server provides access to a single database for reading and writing (dependent on the needed security permissions). When a document is read or written via WebDAV, all of its associated data, such as properties, metadata, collections, and so on are also transferred with the document.

In the Admin Interface, you configure a WebDAV server to access a database. Documents stored in that database are accessible for reading via HTTP. The database is also accessible via WebDAV clients for reading, modifying, deleting, and adding documents. When you add a document via a WebDAV client (by dragging and dropping, for example), you are actually loading a document directly into the database.

When accessing a database via a WebDAV server, you cannot execute XQuery code. Unlike an HTTP server, there is no Modules database for a WebDAV server. You can, however, configure a database as the Modules database of an HTTP, ODBC, or XDBC server and you can configure the same database for access from a WebDAV server. Then, you can edit code from the WebDAV server that executes from an HTTP, ODBC, or XDBC server. For an example of this configuration, see Example: Setting Up a WebDAV Server to Add/Modify Documents Used By Another Server.

WebDAV Server Security

WebDAV servers follow the MarkLogic Server security model, as do HTTP, ODBC, and XDBC servers. The server authenticates users with user IDs and passwords stored in the security database for that WebDAV server, and the server controls access to objects in the database with privileges and roles. (Each WebDAV server is connected to a database, and each database is in turn connected to a security database in which security objects such as users are stored.)

You can configure application-level security if you want everyone who accesses the WebDAV server to effectively log in as the same user with no password. For example, if you want everyone to log in as guest, where guest has both read and write privileges and has a predefined set of default privileges, set the authentication scheme to application-level and set the default user to guest.

Because users who have write permissions to the database on a WebDAV server can load documents into the database via a WebDAV client, be sure to configure appropriate default permissions on those users so that documents they load (for example, by dragging and dropping files into a WebDAV folder) have the needed permissions for other users to read and write, according to your security policy. You can achieve such granular access control to the system and to the data through the use of privileges and permissions. For information on using security features in MarkLogic Server, see Security Administration and the chapters related to security in the Application Developer's Guide.

Directories

A WebDAV directory is analogous to a file system directory. A directory must exist in order to view (via a WebDAV client) any documents in that directory (just like in a filesystem, where you must navigate to a directory in order to access any files in that directory). Each document in a directory has a URI that includes the directory URI as a prefix. Also, each directory visible from a WebDAV server must have the WebDAV root as its prefix, and there must exist a directory with the WebDAV root in the database.

For example, if you have a WebDAV root of http://marklogic.com/, then the URI of all documents and all directories must begin with that root in order to be visible from a WebDAV client. Also, the directory with a URI http://marklogic.com/ must exist in the database. Therefore, a document with a URI of http://marklogic.com/file.xml is visible from this WebDAV server, and a directory with a URI of http://marklogic.com/dir/ is also visible. A directory with a URI of /dir/ and a document with a URI of /dir/file.xml is not visible from this server, however, because its URI does not begin with the WebDAV root.

The following sections describe further details about directories:

• Automatic Directory Creation in a Database Settings
• Properties and URIs of Directories

For more details on directories and properties, see the Property Documents and Directories chapter of the Application Developer's Guide.

xdmp:document-properties("/myServer/Marketing/")
=>
<prop:properties xmlns:prop="http://marklogic.com/xdmp/property">
   <prop:directory/>
</prop:properties>

declare namespace prop="http://marklogic.com/xdmp/property"

for $x in xdmp:document-properties()/prop:properties/prop:directory
return <directory-uri>{xdmp:node-uri($x)}</directory-uri>

Server Root Directory

Each WebDAV server has a concept of a root. The root is the top-level directory accessible from the server; you can access any documents or directories in the database that are children of the root. The root therefore serves as a prefix for all document and directory URIs accessible through the WebDAV server. You enter the WebDAV root in the Admin Interface. The root can be any valid URI. The root should always end with a forward slash (/), and if it does not, the Admin Interface will append one to the string provided.

The root should be a unique string that can serve as the top of a directory structure. It is common practice to use a WebDAV root of the form http://<company_domain>/, but that is not required. The following are some examples of WebDAV roots:

http://myCompany/marketing/
/myCompany/marketing/

Directories cannot end in two forward slashes (//). Therefore, you cannot create a directory with a URI http://. If you specify a root of http://myCompany for a WebDAV server and directory creation is set to automatic in the database, a directory with the URI http://myCompany/ is automatically created in the database.

Whatever the root, any documents accessible through the WebDAV server must have URIs that begin with the root. Also, any documents created through a WebDAV client (for example, by dragging and dropping into a web folder) will be loaded with URIs beginning with the WebDAV root.

For example, a document with URI /myCompany/marketing/strategy.doc is accessible (given the necessary security permissions) via the WebDAV server with the root /myCompany/marketing/, and you can create that document by dragging a document named strategy.doc into a web folder configured to access the WebDAV server described above.

When a WebDAV client accesses a WebDAV server whose database has directory creation set to automatic, if the WebDAV root directory does not exist in that database, it is automatically created. The directory is created with no permissions, so it will only be readable by users with the admin role. For other users to be able to use the WebDAV server, you should add appropriate read permissions to the directory (with xdmp:document-add-permissions, for example). For details on document and directory permissions, see Security Guide.

Documents in a WebDAV Server

The main purpose of a WebDAV server is to make it easy for people to store, retrieve, and modify documents in a database. The documents can be any type, whether they are text documents such as .txt files or source code, binary documents such as image files or Microsoft Word files, or XML documents. Because the documents are stored in a database, you can create applications that use the content in those documents for whatever purpose you need. You can also use the database backup and restore features to easily back up the content in the database.

Creating a New WebDAV Server

To create a new server, complete the following steps:

1. Click the Groups icon.
2. Click the group in which you want to define the WebDAV server (for example, Default).
3. Click the App Servers icon on the left tree menu.
4. Click the Create WebDAV tab at the top right.

   The WebDAV Server Create page displays.

5. Go to the WebDAV Server Name field and enter a shorthand name for this WebDAV server.

   MarkLogic Server will use this name to refer to this server on display screens and in user interface controls.

6. Go to the root field and enter the name of WebDAV root. This root is a string that represents the top-level of the WebDAV URI hierarchy. Any document accessible through this WebDAV server must have a URI that begins with this root string. For more details on the root, see Server Root Directory.

   If the root directory does not contain a forward slash, the Admin Interface adds one for you.

7. Go to the Port field and enter the port number through which you want to make this WebDAV server available. The port number must not be assigned to any other server.
8. Go to the Database field and select the database to be accessed by this WebDAV server.

   Multiple HTTP, ODBC, XDBC, and WebDAV servers can be connected to the same database.

   If you are using a database with a WebDAV server, the directory creation setting on the database should be set to automatic, which will automatically create the root directory and other directories for any documents added to the database (if the directory does not already exist). For more information on directories, see Directories.

9. Scroll to the Authentication field. Select an authentication scheme, as described in Types of Authentication in the Security Guide. The default is digest, which uses encrypted passwords.

   

   If you select application-level authentication, you will also need to fill in a Default User. Any one accessing the App Server server is automatically logged in as the Default User until the user logs in explicitly.

   

   If you use an admin user (admin) as the Default User (an authorized administrator with the admin role), then everyone who uses this App Server is automatically a user with the admin role, which effectively turns off security for this App Server.

10. Scroll to the Privilege field near the bottom of the screen. This field represents the privilege needed to access (login) the server. You may leave this field blank.
11. Set any other properties for this App Server, as appropriate to your needs:
    • Last Login and Display Last Login are described in Storing and Monitoring the Last User Login Attempt.
    • Backlog specifies the maximum number of pending connections allowed on the HTTP server socket.
    • Threads specifies the maximum number of App Server threads.
    • Request Timeout specifies the maximum number of seconds before a socket receives a timeout for the first request.
    • Keep Alive timeout specifies the maximum number of seconds before a socket receives a timeout for subsequent requests over the same connection.
    • Session Timeout specifies the maximum number of seconds before an inactive session times out.
    • Max Time Limit specifies the upper bound for any request's time limit. No request may set its time limit (for example with xdmp:set-request-time-limit) higher than this number. The time limit, in turn, is the maximum number of seconds allowed for servicing a query request. The App Server gives up on queries which take longer, and returns an error.
    • Default Time Limit specifies the default value for any request's time limit, when otherwise unspecified. A request can change its time limit using xdmp:set-request-time-limit. The time limit, in turn, is the maximum number of seconds allowed for servicing a query request. The App Server gives up on queries which take longer, and returns an error.
    • Static Expires adds an "expires" HTTP header for static content to expire after this many seconds.
    • Pre-commit Trigger Limit specifies the maximum number of pre-commit triggers a single statement against this App Server can invoke. For more information on triggers, see Using Triggers to Spawn Actions in the Application Developer's Guide.
    • Pre-commit Trigger Depth specifies the maximum depth (how many triggers can cause other triggers to fire, which in turn cause others to fire, and so on) for pre-commit triggers that are executed against this App Server. For more information on triggers, see Using Triggers to Spawn Actions in the Application Developer's Guide.
    • Collation specifies the default collation for queries run in this appserver. This will be the collation used for string comparison and sorting if none is specified in the query. For details, see Encodings and Collations in the Search Developer's Guide.
    • Concurrent Request Limit specifies the maximum number of requests any user may have running at a specific time. 0 indicates no maximum. For details, see Managing Concurrent User Sessions.
    • Log Errors specifes whether to log uncaught errors for this App Server to the ErrorLog.txt file. This is useful to log exceptions that might occur on an App Server for later debugging.
    • Debug Allow specifies whether to allow requests against this App Server to be stopped for debugging, using the MarkLogic Server debugging APIs.
    • Profile Allow specifies whether to allow requests against this App Server to be profiled, using the MarkLogic Server profiling APIs. For details, see Profiling Requests to Evaluate Performance in the Query Performance and Tuning guide.
    • Default XQuery Version specifies the default XQuery language for this App Server if an XQuery module does explicitly declare its language version.
    • Multi Version Concurrency Control specifies how strict queries behave about getting the latest timestamp. This only affects query statements, not update statements. For details about queries and transactions in MarkLogic Server, see Understanding Transactions in MarkLogic Server in the Application Developer's Guide.
    • The properties associated with SSL support are described in Configuring SSL on App Servers in the Security Guide.
12. Scroll to the top or bottom and click OK.

The new WebDAV server is added. Adding a WebDAV server is a hot admin task.

Setting Output Options for a WebDAV Server

For each WebDAV Server, you can set various default output options. These output options affect how data returned from the App Server is serialized. You can also set these options at the query level to override any default options. You can set serialization options to override the App Server defaults in XQuery with the declare option XQuery prolog, and in XSLT using the <xsl:output> instruction. For details on setting the serialization options in XQuery, see Declaring Options in the XQuery and XSLT Reference Guide. For XSLT output details, see the XSLT specification (http://www.w3.org/TR/xslt20#serialization).

To specify defaults for the App Server, complete the following steps:

1. Click the Groups icon in the left tree menu.
2. Click the group which contains the WebDAV server you want to view (for example, Default).
3. Click the App Servers icon on the left tree menu.
4. Select the App Server to edit.
5. Select the Output Options link in the left tree menu. The Output Options Configuration page displays.
6. Set any options that you want to control for this App Server.
7. Click OK to save your changes.

For more details about App Server output, see Controlling App Server Access, Output, and Errors in the Application Developer's Guide.

Viewing WebDAV Server Settings

To view the settings for a WebDAV server, complete the following steps:

1. Click the Groups icon.
2. Click the group which contains the WebDAV server you want to view (for example, Default).
3. Click the App Servers icon on the left tree menu.
4. Locate the WebDAV server for which you want to view settings, either in the tree menu or on the summary page.
5. Click the icon for this WebDAV server.
6. View the settings.

Deleting a WebDAV Server

To delete the settings for a WebDAV server, complete the following steps:

1. Click the Groups icon.
2. Click the group which contains the WebDAV server you want to delete (for example, Default).
3. Click the WebDAVServers icon on the left tree menu.
4. Click the Configure tab at the top right.
5. Locate the WebDAV server to be deleted, either in the tree menu or on the summary page.
6. Click the icon for this WebDAV server.
7. Click Delete.
8. A confirmation message displays. Confirm the delete and click OK.

Deleting a WebDAV server is a cold admin task; the server restarts to reflect your changes.

Tested WebDAV Clients

The following table lists WebDAV clients that have been tested with MarkLogic Server:

For detailed information on these clients, see the documentation accompanying these products.

Directory and document names in WebDAV (and in MarkLogic Server databases) are case-sensitive, but some WebDAV clients (Windows Explorer, for example) are not case-sensitive. While Windows recognizes case, it treats the directory named NewFolder as the same directory as one named newFolder. Therefore, directory or document names that differ only in case might cause confusion when using Windows Explorer or other case-insensitive WebDAV clients. If possible, avoid assigning names to directories or documents that differ only by case (for example, NewFolder vs newFolder).

Windows Vista and Windows 7 WebDAV clients will cause two transactions upon initial document creation: the first is a 0-length WebDAV PUT resulting in a new 0-length document, and the second is an update to the 0-length document. If you are using CPF (or other applications that use triggers), this will fire both the create trigger (when the initial 0-length document is created) and the update trigger (when the document is updated with its contents). When using Vista or Windows 7 WebDAV clients with CPF applications, make sure that your CPF actions for create and update are designed to work correctly for this behavior. In most cases, having the same action for create and update will be sufficient, but in some cases, you might need to write an action that checks for a 0-length document and does something special with it.

General Steps to Connect to a Server

Each WebDAV client has its own way of connecting to a WebDAV server, but the general steps to connect to a WebDAV server are as follows:

1. Start the WebDAV client.
2. Enter the connection information for the WebDAV server. This includes the servername and port number of the WebDAV server. For example, if you have a WebDAV server running on port 9001 on a machine named marklogic.myCompany.com, enter the following URL in the appropriate place for your WebDAV client:

   http://marklogic.myCompany.com:9001/

3. If prompted, enter a username and password for the WebDAV server. You will be prompted for a username or password unless you have configured application-level security.

   The user who logs into the WebDAV server must have the needed privileges (granted via roles) to access the documents and directories under the WebDAV root directory. Also, if you want the WebDAV user to create documents under the WebDAV root, then that user must have the needed URI privileges (granted via roles) to create documents under the root. The lack of any needed privileges and/or permissions can cause the WebDAV login or other WebDAV activities to fail. For details on URI privileges and document permissions, see Security Guide.

4. Use whatever browsing mechanism the client supports to add, remove, or modify documents and directories. For example, in Windows Explorer, double click on folders to expand them, drag and drop documents into folders, rename documents and directories, and so on.

Steps to Connect to a Web Folder in Windows Explorer

If you are running Windows, perform the following steps to use the Windows Explorer WebDAV client:

1. Double-click the My Network Places icon on your desktop.
2. In My Network Places, double-click the Add Network Places icon.
3. In the Add Network Place Wizard, enter your WebDAV server address and port number. For example, if you have a WebDAV server running on port 9001 on a machine named marklogic.myCompany.com, enter the following URL:

   http://marklogic.myCompany.com:9001/

4. Click Next.
5. If prompted, enter your username and password for the WebDAV server.
6. Enter a name for the network place and click finish.

You can now use this folder like other Windows folders to drag and drop documents, rename documents, and so on. When you drag and drop a file into a WebDAV folder connected to a MarkLogic Server WebDAV server, you will actually load that document into the database.