.\"
.\" Copyright (c) 2006-2017 Apple Inc. All rights reserved.
.\"
.\" Licensed under the Apache License, Version 2.0 (the "License");
.\" you may not use this file except in compliance with the License.
.\" You may obtain a copy of the License at
.\"
.\"     http://www.apache.org/licenses/LICENSE-2.0
.\"
.\" Unless required by applicable law or agreed to in writing, software
.\" distributed under the License is distributed on an "AS IS" BASIS,
.\" WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
.\" See the License for the specific language governing permissions and
.\" limitations under the License.
.\"
.\" The following requests are required for all man pages.
.Dd June 17, 2009
.Dt CALENDARSERVER_MANAGE_PRINCIPALS 8
.Os
.Sh NAME
.Nm calendarserver_manage_principals
.Nd Calendar Server principal management utility
.Sh SYNOPSIS
.Nm
.Op Fl -config Ar file
.Op Fl -verbose
.Op Fl -read-property Ar property
.Op Fl -list-principal-types
.Op Fl -list-principals Ar type
.Op Fl -search Ar search-string
.Op Fl -list-read-proxies
.Op Fl -list-write-proxies
.Op Fl -list-proxies
.Op Fl -add-read-proxy Ar principal
.Op Fl -add-write-proxy Ar principal
.Op Fl -remove-proxy Ar principal
.Op Fl -set-auto-schedule-mode Ar none|accept-always|decline-always|accept-if-free|decline-if-busy|automatic
.Op Fl -get-auto-schedule-mode
.Op Fl -set-auto-accept-group Ar group
.Op Fl -get-auto-accept-group
.Op Fl -add Ar locations|resources full-name\: [record-name] [GUID]
.Op Fl -remove
.Ar principal
.Op principal ...
.Sh DESCRIPTION
.Nm
is a tool for accessing and manipulating information regarding
principals on a Calendar Server.  Principals represent any form of
actor that can access the server, such as users, groups, locations and
resources.
.Pp
.Nm
should be run as a user with the same privileges as the Calendar
Server itself, as it needs to read and write data that belongs to the
server.
.Nm
takes a list of principals as arguments and then performs the
requested actions on each of the given principals.
.Pp
A principal may be specified as the principal's GUID. Alternatively,
it may be specified in the form
.Ar recordType:shortName ,
where
.Ar recordType
is a
directory record type (eg.
.Ar users ,
.Ar groups ,
.Ar locations ,
.Ar resources )
and
.Ar shortName
is the principal's short name.
.Pp
Actions to perform are specified via the options below.  Multiple
actions may be given, and will be performed in the order given on
each principal specified.
.Sh OPTIONS
.Bl -tag -width flag
.It Fl h, -help
Displays usage information
.It Fl v, -verbose
Displays debugging information
.It Fl f, -config Ar FILE
Use the Calendar Server configuration specified in the given file.
Defaults to /etc/caldavd/caldavd.plist.
.El
.Sh ACTIONS
.Bl -tag -width flag
.It Fl -read-property Ar property
Read the given WebDAV property on the principal resource.
.Ar property
must be a fully qualified XML element name in the form
.Ar {namespace}name ,
for example:
.Ar {DAV:}displayname .
.It Fl -list-principal-types
List all of the known principals types.
.It Fl -list-principals Ar type
List all of the principals of the given type.
.It Fl -search Ar search-string
Search for principals whose name or email address contains the search
string.
.It Fl -list-read-proxies
List the read proxies.
.It Fl -list-write-proxies
List the write proxies.
.It Fl -list-proxies
List all proxies.
.It Fl -add-read-proxy Ar principal
Add the given
.Ar principal
as a read proxy.
.It Fl -add-write-proxy Ar principal
Add the given
.Ar principal
as a write proxy.
.It Fl -remove-proxy Ar principal
Remove the given
.Ar principal
as a proxy.
.It Fl -set-auto-schedule Ar true|false
Enable or disable automatic scheduling.
.It Fl -get-auto-schedule
Get the automatic scheduling state.
.It Fl -set-auto-accept-group Ar group
The principal will auto-accept any invites from any member of the group (as long
as there are no conflicts).
.It Fl -get-auto-accept-group
Get the currently assigned auto-accept group for the principal.
.It Fl -add Ar locations|resources full-name [record-name] [GUID]
Add a new location or resource. Record name and GUID are optional.  If
GUID is not specified, one will be generated.  If record name is not
specified, the record name will be set to the GUID.
.El
.Sh EXAMPLES
Add Alice and Bob as read proxies for Joe and display the list of
Joe's proxies:
.Pp
.Dl "calendarserver_manage_principals --add-read-proxy users:alice --add-read-proxy users:bob --list-proxies users:joe"
.Pp
Add a group of room admins as write proxy for a couple of rooms:
.Pp
.Dl "calendarserver_manage_principals --add-write-proxy groups:room-admins locations:bigroom locations:littleroom"
.Pp
Turn on auto-scheduling for a resource, and confirm the setting:
.Pp
.Dl "calendarserver_manage_principals --set-auto-schedule true --get-auto-schedule resources:projector"
.Pp
Search for all principals named Joe:
.Pp
.Dl "calendarserver_manage_principals --search joe"
.Pp
Add a location:
.Pp
.Dl "calendarserver_manage_principals --add locations 'Example Office' office1"
.Pp
Add a resource:
.Pp
.Dl "calendarserver_manage_principals --add resources 'Example Projector' proj1"
.Pp
List all resource:
.Pp
.Dl "calendarserver_manage_principals --list-principals resources"
.Pp
Remove a resource:
.Pp
.Dl "calendarserver_manage_principals --remove resources:proj1"
.Pp
.Sh FILES
.Bl -tag -width flag
.It /etc/caldavd/caldavd.plist
The Calendar Server configuration file.
.El
.Sh SEE ALSO
.Xr caldavd 8