API docs by Redocly

ceod - OpenAPI 3.0 (1.0.0)

Download OpenAPI specification:Download

E-mail: syscom@csclub.uwaterloo.ca

This is an OpenAPI specification of ceod, the CSC Electronic Office daemon. Visit the git repository for more details.

Streaming Responses

Many endpoints return a "streaming response", which consists of a series of JSON objects, one per line (the mimetype is text/plain). For example:

{"status": "in progress", "operation": "replace_login_shell"}
{"status": "in progress", "operation": "replace_forwarding_addresses"}
{"status": "completed", "result": "OK"}

Whenever an operation is completed, a corresponding JSON object will be streamed from the server to the client. This allows the client to track the server's progress in real time.

members

Operations on members and club reps

Create a new user

Creates a new member or club rep. If terms is specified, a member is created; if non_member_terms is specified, a club rep is created.

Authorizations:
GSSAPIAuth
Request Body schema: application/json
uid
string (UID)

Username

cn
string (UserCN)

Full name

sn
string (UserSN)

Last name

given_name
string (UserGivenName)

First name

program
string (Program)

Academic program

integer or Array of Terms (strings) (TermsOrNumTerms)
integer or Array of Terms (strings) (TermsOrNumTerms)
forwarding_addresses
Array of strings <email> (ForwardingAddresses)

Forwarding addresses in ~/.forward

Responses

Request samples

Content type
application/json
{
  • "uid": "ctdalek",
  • "cn": "Calum Dalek",
  • "sn": "Dalek",
  • "given_name": "Calum",
  • "program": "MAT/Mathematics Computer Science",
  • "terms": 1,
  • "non_member_terms": 1,
  • "forwarding_addresses": [
    ]
}

Response samples

Content type
text/plain
{"status": "in progress", "operation": "add_user_to_ldap"}
{"status": "in progress", "operation": "add_group_to_ldap"}
{"status": "in progress", "operation": "add_user_to_kerberos"}
{"status": "in progress", "operation": "create_home_dir"}
{"status": "in progress", "operation": "send_welcome_message"}
{"status": "in progress", "operation": "subscribe_to_mailing_list"}
{"status": "in progress", "operation": "announce_new_user"}
{"status": "completed", "result": {"cn": "Calum Dalek", "given_name": "Calum", "sn": "Dalek", "uid": "ctdalek", "uid_number": 20001, "gid_number": 20001, "login_shell": "/bin/bash", "home_directory": "/users/ctdalek", "is_club": false, "program": "MAT/Mathematics Computer Science", "terms": ["f2021"], "forwarding_addresses": ["ctdalek@uwaterloo.ca"], "password": "Wlw1wOTofERTEBlXWzR6/MZL"}}

Get information about a user

Returns information about a member or club rep. The forwarding_addresses field will only be present if the client is an authenticated syscom member.

Authorizations:
GSSAPIAuth
path Parameters
username
required
string

username of the user to return

Responses

Response samples

Content type
application/json
{
  • "cn": "Calum Dalek",
  • "sn": "Dalek",
  • "given_name": "Calum",
  • "uid": "ctdalek",
  • "uid_number": 20001,
  • "gid_number": 20001,
  • "home_directory": "/users/ctdalek",
  • "is_club": false,
  • "login_shell": "/bin/bash",
  • "program": "MAT/Mathematics Computer Science",
  • "positions": [
    ],
  • "terms": [
    ],
  • "non_member_terms": [
    ],
  • "forwarding_addresses": [
    ],
  • "groups": [
    ]
}

Modify a user

Replace the login shell and/or forwarding addresses of a user

Authorizations:
GSSAPIAuth
path Parameters
username
required
string

username of the user to modify

Request Body schema: application/json
login_shell
string (LoginShell)

Login shell

forwarding_addresses
Array of strings <email> (ForwardingAddresses)

Forwarding addresses in ~/.forward

Responses

Request samples

Content type
application/json
{
  • "login_shell": "/bin/bash",
  • "forwarding_addresses": [
    ]
}

Response samples

Content type
text/plain
{"status": "in progress", "operation": "replace_login_shell"}
{"status": "in progress", "operation": "replace_forwarding_addresses"}
{"status": "completed", "result": "OK"}

Renew a user

Add member or non-member terms to a user

Authorizations:
GSSAPIAuth
path Parameters
username
required
string

username of the user to renew

Request Body schema: application/json
One of
integer or Array of Terms (strings) (TermsOrNumTerms)

Responses

Request samples

Content type
application/json
{
  • "terms": [
    ]
}

Response samples

Content type
application/json
{
  • "terms_added": [
    ]
}

Reset a user's password

Sets a user's password to a randomly generated string, and returns it. The user will be prompted to set a new password on their next login.

Authorizations:
GSSAPIAuth
path Parameters
username
required
string

username of the user whose password will be reset

Responses

Response samples

Content type
application/json
{
  • "password": "EPGbJwLl1pmiWz8Wvu/MSs+v"
}

groups

Operations on groups and clubs

Create a new group

Creates a new Unix group for a club. A new Unix user account with the same name will also be created. A sudo role will be created allowing members of the group to become this user.

Authorizations:
GSSAPIAuth
Request Body schema: application/json
cn
string (GroupCN)

the name of the group

description
string (GroupDescription)

a description of the group

Responses

Request samples

Content type
application/json
{
  • "cn": "uwclub1",
  • "description": "Club One"
}

Response samples

Content type
text/plain
{"status": "in progress", "operation": "add_user_to_ldap"}
{"status": "in progress", "operation": "add_group_to_ldap"}
{"status": "in progress", "operation": "add_sudo_role"}
{"status": "in progress", "operation": "create_home_dir"}
{"status": "completed", "result": {"cn": "uwclub1", "gid_number": 30001, "description": "Club One", "members": []}}

Get information about a group

Returns information about a group

path Parameters
group_name
required
string

name of the group to return

Responses

Response samples

Content type
application/json
{
  • "cn": "uwclub1",
  • "description": "Club One",
  • "gid_number": 20001,
  • "members": [
    ]
}

Add a member to a group

Adds a member to a group. The member will also be added to any auxiliary groups specified in ceod.conf. The member may also be added to auxiliary mailing lists.

Authorizations:
GSSAPIAuth
path Parameters
group_name
required
string

name of the group to which the member will be added

username
required
string

username of the member who will be added to the group

query Parameters
subscribe_to_lists
boolean
Default: true

whether the member should be subscribed to auxiliary mailing lists

Responses

Response samples

Content type
text/plain
{"status": "in progress", "operation": "add_user_to_group"}
{"status": "in progress", "operation": "add_user_to_auxiliary_groups"}
{"status": "in progress", "operation": "subscribe_user_to_auxiliary_mailing_lists"}
{"status": "completed", "result": {"added_to_groups": ["group2","group3"], "subscribed_to_lists": ["list1","list2"]}}

Remove a member from a group

Removes a member from a group. The member will also be removed from any auxiliary groups specified in ceod.conf. The member may also be removed from auxiliary mailing lists.

Authorizations:
GSSAPIAuth
path Parameters
group_name
required
string

name of the group from which the member will be removed

username
required
string

username of the member who will be removed from the group

query Parameters
unsubscribe_from_lists
boolean
Default: true

whether the member should be unsubscribed from auxiliary mailing lists

Responses

Response samples

Content type
text/plain
{"status": "in progress", "operation": "remove_user_from_group"}
{"status": "in progress", "operation": "remove_user_from_auxiliary_groups"}
{"status": "in progress", "operation": "unsubscribe_user_from_auxiliary_mailing_lists"}
{"status": "completed", "result": {"removed_from_groups": ["group2","group3"], "unsubscribed_from_lists": ["list1","list2"]}}

mailman

Operations on mailing list subscriptions

subscribe a user to a mailing list

Subscribes a user to a mailing list.

Authorizations:
GSSAPIAuth
path Parameters
mailing_list
required
string

The name of the list to which the user will be subscribed. If there is no '@' symbol, then '@csclub.uwaterloo.ca' will be appended to the list name.

username
required
string

The user who will be subscribed to the list. If there is no '@' symbol, then '@csclub.uwaterloo.ca' will be appended to he username; otherwise, the given email address will be subscribed.

Responses

Response samples

Content type
application/json
{
  • "result": "OK"
}

unsubscribe a user from a mailing list

Unsubscribes a user from a mailing list.

Authorizations:
GSSAPIAuth
path Parameters
mailing_list
required
string

The name of the list from which the user will be unsubscribed. If there is no '@' symbol, then '@csclub.uwaterloo.ca' will be appended to the list name.

username
required
string

The user who will be unsubscribed from the list. If there is no '@' symbol, then '@csclub.uwaterloo.ca' will be appended to he username; otherwise, the given email address will be unsubscribed.

Responses

Response samples

Content type
application/json
{
  • "result": "OK"
}

uwldap

Operations related to the UW LDAP directory

get UWLDAP information for a user

Returns information about a user from the UW LDAP directory.

path Parameters
username
required
string

username of the user to return

Responses

Response samples

Content type
application/json
{
  • "uid": "ctdalek",
  • "cn": "Calum Dalek",
  • "given_name": "Calum",
  • "sn": "Dalek",
  • "mail_local_addresses": [
    ]
}

update CSC programs from UWLDAP

Sync the 'program' attribute in the CSC LDAP with the UW LDAP. The JSON request body may be omitted.

Authorizations:
GSSAPIAuth
query Parameters
dry_run
boolean
Default: false

Whether to perform a dry run or not. If true, a list of members who would have been changed is returned.

Request Body schema: application/json
members
Array of strings (UID)
Default: []

If non-empty, only these members will be synced with UWLDAP

Responses

Request samples

Content type
application/json
{
  • "members": [ ]
}

Response samples

Content type
application/json
[
  • [
    ]
]

database

Operations related to databases

Create a MySQL database

Create a MySQL database for the user

Authorizations:
GSSAPIAuth
path Parameters
username
required
string

name of the user to create MySQL database for

Responses

Response samples

Content type
application/json
{
  • "password": "7fUi5rQr/lcpeEj4M86ZBbwM"
}

Reset MySQL database password

Reset the password for a user's MySQL database

Authorizations:
GSSAPIAuth
path Parameters
username
required
string

name of the user to reset the MySQL database password for

Responses

Response samples

Content type
application/json
{
  • "password": "kM90d3G/eofIUxr9O3CQHTlP"
}

Create a PostgreSQL database

Create a PostgreSQL database for the user

Authorizations:
GSSAPIAuth
path Parameters
username
required
string

name of the user to create PostgreSQL database for

Responses

Response samples

Content type
application/json
{
  • "password": "iHxd62DC7Qt1HyYRj18P6ujS"
}

Reset PostgreSQL database password

Reset the password for a user's PostgreSQL database

Authorizations:
GSSAPIAuth
path Parameters
username
required
string

name of the user to reset the PostgreSQL database password for

Responses

Response samples

Content type
application/json
{
  • "password": "CdPHT49iYAWzzKuhKTt2dNeu"
}

cloud

Operations related to the CSC Cloud

Activate a cloud account

Activate a cloud account for the calling user

Authorizations:
GSSAPIAuth

Responses

Response samples

Content type
application/json
{
  • "status": "OK"
}

Purge expired accounts

Delete the cloud accounts of expired members.

There is a one-month grace period after the expiration. After one month, expired members will be sent an email warning them that their account will be deleted. One week after that, if an expired member has still not renewed their membership, their account will be deleted.

Authorizations:
GSSAPIAuth

Responses

Response samples

Content type
application/json
{
  • "accounts_to_be_deleted": [
    ],
  • "accounts_deleted": [
    ]
}

Create a vhost

Add a new virtual host configuration.

Authorizations:
GSSAPIAuth
path Parameters
domain
required
string

domain name of the virtual host

Request Body schema: application/json
ip_address
string

IP address of the virtual host

Responses

Request samples

Content type
application/json
{
  • "ip_address": "172.19.134.11"
}

Response samples

Content type
application/json
{
  • "status": "OK"
}

Delete a vhost

Delete a virtual host configuration.

Authorizations:
GSSAPIAuth
path Parameters
domain
required
string

domain name of the virtual host

Responses

Response samples

Content type
application/json
{
  • "status": "OK"
}

List all vhosts

List all virtual host configurations for the calling user.

Authorizations:
GSSAPIAuth

Responses

Response samples

Content type
application/json
{
  • "vhosts": [
    ]
}

Activate a Kubernetes account

Create a Kubernetes namespace for the calling user. A new kubeconfig file will be returned. If the namespace already exists, the certificate inside the kubeconfig will be renewed.

Authorizations:
GSSAPIAuth

Responses

Response samples

Content type
application/json
{
  • "status": "OK",
  • "kubeconfig": "string"
}

positions

Show current positions

Shows the list of positions and members holding them.

Authorizations:
GSSAPIAuth

Responses

Response samples

Content type
application/json
{
  • "president": [
    ],
  • "vice-president": [
    ],
  • "sysadmin": [
    ],
  • "treasurer": null
}

Update positions

Update members for each positions. Members not specified in the parameters will be removed from the position and unsubscribed from the exec's mailing list. New position holders will be subscribed to the mailing list.

Authorizations:
GSSAPIAuth
Request Body schema: application/json

New position holders

additional property
string or Array of strings

Responses

Request samples

Content type
application/json
{
  • "president": "user1",
  • "vice-president": "user2, user3",
  • "secretary": [
    ],
  • "sysadmin": [
    ],
  • "treasurer": null
}

Response samples

Content type
text/plain
{"status": "in progress", "operation": "update_positions_ldap"}
{"status": "in progress", "operation": "update_exec_group_ldap"}
{"status": "in progress", "operation": "subscribe_to_mailing_list"}
{"status": "completed", "result": {"president": ["user1"],"vice-president": ["user2", "user3"],"secretary": ["user4". "user5"],"sysadmin": ["user6"]}}