Cosmo End User Manual

This manual describes Cosmo 0.3. The previous version of this document can be found at CosmoZeroTwoEndUser.

This document does not address installation or configuration of the server. All administrative issues are documented at CosmoAdministrator.

These instructions assume that your administrator has installed Cosmo on localhost and is not using SSL, so that the base URL for Cosmo is http://localhost:8080/cosmo/ (this is the default configuration of the OSAF server bundle). Check with your administrator if you have any questions about the URL for Cosmo.

User Accounts

In order to share content to Cosmo, you must create a user account identified uniquely by a username and an email address. Doing so creates a home directory where you can store data. You can access this home directory via WebDAV (you can mount it on your desktop in Windows, OS X and Linux or use a command line program like cadaver) and CalDAV (calendar clients such as Chandler, Scooby, Sunbird, and Evolution). You can also browse your home directory with Cosmo's web console.

Sign Up for an Account

1. Access the Cosmo web console in a web browser at http://localhost:8080/cosmo/.
2. Find the paragraph that begins Don't have an account? and click the link that says Click here to create one.
3. You should now see the Create New Account form. Fill out the entire form, as all of the fields are required.
   • Usernames may contain just about any character, including spaces and punctuation marks. The only exceptions are forward slash ('/'), control characters and whitespace characters other than space (' '). Usernames may be at least 3 characters and at most 32 characters long. You cannot choose a username that has already been taken by another account on this server.
   • First name and last name may contain any character. Each may be up to 128 characters long.
   • Email address must be a valid RFC 822 email address that can actually receive mail (it should not bounce mail). It may be up to 128 characters long. You cannot use an email address that is already associated with another account on this server.
   • Password and and confirm password must (obviously) match. The password may contain must be between 5 and 16 characters long and may contain any character.
4. Click the Create Account button.
5. That's it! The resulting page displays your account details, including the URL of your Cosmo home directory (eg http://localhost:8080/cosmo/home/bcm/).

Note that your home directory is not a calendar. It is just a place in the server to put your data.

Publishing and Subscribing to Calendars

Cosmo supports two kinds of calendars:

• "webcal", in which an entire calendar is stored on the server in a single resource (file). This is the format popularized by iCal and supported by just about every calendar client, but it is too limited to allow effective read-write subscriptions; usually only the person who published the calendar can update it.
• CalDAV, where a calendar is represented on the server as a collection (folder), and each event is stored inside the calendar collection as a separate resource. This format makes read-write subscription (real calendar sharing) possible, and it makes syncing medium- and large-sized calendars much easier.

Cosmo has the ability to make a CalDAV calendar masquerade as a webcal resource, so that clients which only support webcal can still subscribe (read-only) to CalDAV calendars. Cosmo does not allow webcal clients to update subscribed CalDAV calendars.

Supported Clients

These clients have been tested with Cosmo 0.3.

• OSAF Chandler 0.6, 0.7
• OSAF Scooby 0.1, 0.2
• Apple iCal 2.0
• Mozilla Sunbird 0.3
• Evolution 2.6

If your favorite client is not on this list, see if you can get it working using the instructions for the above clients as starting points. If you are successful, please add to this list:

• Mozilla Lightning 0.1

Controlling Access to Your Calendars

Once you have published a calendar to Cosmo, only you (and Cosmo administrators) have access to it. In order to allow others to view and potentially edit your calendars, you must explicitly grant them access.

Note that everything in this section applies equally to any resource inside your home directory, including files you might upload using WebDAV.

Tickets

The only type of access control currently implemented by Cosmo is based on tickets. These are like airline tickets that prove you are able to board a plane. Unlike airline tickets, though, Cosmo does not force you to provide ID that proves you are a specific person. Anybody in the world can use a ticket to access a Cosmo resource. This means you can create one ticket and give it to many different people to grant them access to your calendar.

Tickets are uniquely identified with random strings like "0fc3bd0a5f2". Each ticket is associated with a set of privileges; Cosmo supports read-only and read-write tickets. Tickets can also have expiration dates, or "timeouts", althought they don't have to. Setting a ticket to expire after a certain amount of time is a good way to provide limited, time-based access to a resource.

Tickets can be inherited from their ancestor collections. Imagine that you published three calendars into your home directory and then created a single read-only ticket on the home directory itself. Once you've given your friend the ticket, he can look at any of those calendars (along with anything else in your home directory). If you instead had created the ticket on one of the calendars, then your friend could only look at that calendar, but the other calendars would remain private.

The following instructions assume that you have previously published a webcal calendar named Home.ics into your home directory.

Granting a Ticket

You can use the home directory browser built into Cosmo's web console to grant tickets on your calendars.

1. Log into Cosmo.
2. Click the Browse your home directory link.
3. You are now looking at a page that shows lots of things about your home directory, including basic attributes like when it was created as well as lists of its member resources, tickets, and properties.
4. Find Home.ics in the contents list and click its Browse link. (You may notice that Cosmo thinks the calendar is a "File" rather than a "Calendar". This is because it's a webcal calendar, which Cosmo treats for almost all purposes like a regular file, because it's a legacy format).
5. You now see a similar page to the previous one, but this time for Home.ics. Several more attributes about the resource are displayed, including its size and creation and modification times.
6. Click the new ticket link in the Tickets section.
7. Optionally enter a number of seconds in the Timeout box. If you don't enter anything, the ticket will never expire.
8. Select the Read radio button unless you want the ticket to be Read/Write, which is the default selection.
9. Click Grant Ticket.
10. You are now viewing the Home.ics page again, and your new ticket appears in the Tickets section.

Revoking a Ticket

If a ticket has served its purpose but hasn't yet expired (or never will), you can remove it using the home directory browser.

1. Follow the instructions above to navigate to the Home.ics page.
2. Locate the ticket in the Tickets section and click its Revoke link.
3. The Home.ics page refreshes, but the ticket has been removed from the Tickets section.

Constructing a Ticket-Bearing Calendar URL

Once you have published a calendar and granted a ticket on it, you can share the calendar with a friend (let's call him Bobby). You need to tell Bobby the URL of the calendar you published, and you have make sure that the URL contains the ticket you granted.

Notice that the Tickets section of each home directory browser page in the web console includes WebDAV/CalDAV and Atom feed links for each ticket. You can right-click these links to copy the URLs and paste them into other applications, for instance to send Bobby an email.

You can also construct ticket-bearing URLs manually. Assume a calendar published at http://localhost:8080/cosmo/home/bcm/Home.ics To embed the ticket into this calendar URL, simply add ?ticket=<ticket-id> where <ticket-id> is replaced with the id of a ticket that you granted on Home.ics. You can find the id by looking in the home directory browser as described above. Now the calendar URL is http://localhost:8080/cosmo/home/bcm/Home.ics?ticket=0fc3bd0a5f2.

Contributors

• Brian Moseley
• Brad Lauster
• Mike Taylor
• Mimi Yin
• Christopher Tengi