Browse Source

Updated content

pull/1/head
Hamzah 3 months ago
parent
commit
95e5aaf93b
4 changed files with 215 additions and 123 deletions
  1. +59
    -0
      docs/api.md
  2. +14
    -7
      docs/index.md
  3. +129
    -99
      docs/procedures.md
  4. +13
    -17
      mkdocs.yml

+ 59
- 0
docs/api.md View File

@@ -0,0 +1,59 @@
# API

## Redbrick Administrator Web API

The Redbrick web API is serves as an easy interface to carry out administrator tasks (mainly LDAP related), and for use in automation.

This saves time instead of accessing machines, and formulating and executing manual LDAP queries or scripts.

### Reference

For the most up to date, rich API reference please visit [https://api.redbrick.dcu.ie/docs](https://api.redbrick.dcu.ie/docs)

All requests are validated with Basic Auth for access. [See example.](https://docs.python-requests.org/en/master/user/authentication/#basic-authentication)


| Method | Route | URL Parameters | Body |
| :--------: | :--------------------: | :----------------------------------: | :---------------: |
| GET | **/users/**`username` | `username` - Redbrick username | N/A |
| PUT | **/users/**`username` | `username` - Redbrick username | `ldap_key` |
| POST | **/users/register** | N/A | `ldap_value` |

#### Examples

GET a user's LDAP data
```python
import requests

url = "https://api.redbrick.dcu.ie/users/USERNAME_HERE"

headers = {
'Authorization': 'Basic <ENCODED_USERANDPASS_HERE>'
}

response = requests.request("GET", url, headers=headers)

print(response.text)
```

PUT a user's LDAP data to change their `loginShell` to `/usr/local/shells/zsh`
```python
import requests
import json

url = "https://api.redbrick.dcu.ie/users/USERNAME_HERE"
payload = json.dumps({
"ldap_key": "loginShell",
"ldap_value": "/usr/local/shells/zsh"
})
headers = {
'Authorization': 'Basic <ENCODED_USERANDPASS_HERE>',
'Content-Type': 'application/json'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)
```

&emsp;

+ 14
- 7
docs/index.md View File

@@ -5,23 +5,30 @@
The idea of Redbrick documention is to keep an up to date information about the technical infrastructure of Redbrick.
This is mostly intended for admins, future admins, webmasters, and everybody else who is grumpy and has no life.

The search box actually works... Yeah. Me too.
**PS:** The search box *actually* works... please use it for getting around - it's awesome.

## Quick Links

- Daily Operations
- [Services](/services/#index)
- [New Admin Cheatsheet](/cheatsheet/)
- [Redbrick API](/api/)
- [Useful Scripts](/scripts/)
- [Procedures](/procedures/)
- [Monitoring](/monitoring/)
- [Hardware](/hardware/)
- [Network](/network/)
- [Web](/web/)
- [Postmortems](/postmortems/)
- [NixOS](/procedures/#nixos), by jaysus, there's a lot

## New Admins

So, you want to become an admin. Brave of you. Here's some stuff you should probably read:

- [Policies](https://fucking.readthedocs.io/en/latest/procedures/policies)
- [Becoming an admin](/procedures/#new-elected-admins)
- [Policies](/procedures/#redbrick-system-administrator-policies)
- [Abuse at Redbrick](https://fucking.readthedocs.io/en/latest/procedures/abuse), and the committee's stance on it
- [NixOS](https://fucking.readthedocs.io/en/latest/procedures/nixos), by jaysus, there's a lot

## Operations

The day-to-day running of things.

-
&emsp;

+ 129
- 99
docs/procedures.md View File

@@ -1,117 +1,32 @@
# Procedures

## Redbrick System Administrator Policies
## New elected admins

The purpose of this is to brief new Redbrick system administrators on
the current setup, policies and practices in place and to serve as the place to
record all such information for current and future administrators.
The chronological process of becoming an admin usually looks very similar each year. There are some important things you should know.

### Admin Account Priviliges
Remember, being a SysAdmin for the society is *not* a job, it is a volunteered task you sign up to - don't stress yourself out over it, have fun, and hopefully learn a thing or two. : )

- By default, all admin accounts will remain the same as the rest of the
committee.
- Each admin will recieve a local account on each machine that will be
in the root group. This allows you to log on if ldap goes down.
- Accounts should
not be placed into any other 'system' or priviliged accounts (e.g. pgsql, mail,
news, etc.) but by all accounts (hah, bad pun!) can be placed into useful groups
(e.g. cvs, webgroup, helpdesk etc.)
### Process

### Root account

When su'ing to root, please observe the following:

- Wait for the password prompt before typing in the password! Sometimes
lag/terminal freezes or whatever can kick in. The other classic mistake is
typing the password in place of the username (say for a console login).
- Make sure LOGNAME is set to your unix name. The linux boxes will prompt you
for this. On OpenBSD you can use 'su -m' to keep the environment.
- Don't change the root account/finger information!
- If you wish to use another shell, place customisations in your own file. For
bash, `/root/.bash_profile.<USERNAME>` and for zsh `/root/.zshrc.<USERNAME>`.

`/root/.zshrc` and `/root/.bash_profile` source in the appropriate file as long
as `$LOGNAME` is set right (see above). Do not put personal customisations into
the default root account setup, remember other people have to use it.
#### Admin Exam

Common aliases can be put in /root/.profile, familiarise yourself with the
existing ones, they can come in handy.
Anyone wishing to run and be elected as a SysAdmin must complete a technical exam as an assessment of your knowledge and competency in solving some of the many problems that will be thrown at you.

- Please keep `/root` tidy. Don't leave stuff strewn about
the place!
- Make sure to check permissions and ownership on files you work on
**constantly** especially files with important or sensitive information in
them (e.g. always use `cp -p` when copying stuff about).
- Only use root account when absolutely necessary. Many admin tasks can be done
or tested first as a regular user.
You can find some archives of past exams [here](https://github.com/theycallmemac/redbrick-admin-exams/tree/master/exams), however note that these vary year to year as they are created each year by the currently elected admins.

### Gotchas
#### Election at AGM

Couple of things to look out for:
At the annual general meeting, you may nominate yourself, or have someone nominate you to run for SysAdmin. *You may only run if you have passed the Admin exam.*

- `killall` command, never ever use it!
- Alias `cp`, `mv` & `rm` with the `-i` option.
- If you're ever unsure, don't! Ask another admin or check the docs.
- Always always double check commands before firing them off!
The amount of admins per year is usually three, to be elected, you must be in the top three voted members.

### Admin Mailing Lists
#### Onboarding

[lists.redbrick.dcu.ie](lists.redbrick.dcu.ie) (Postorius)
If you are successfully elected - congrats! We welcome you to this <strike>pain</strike> joy filled journey :)

- All accounts in the root group must be on the admin mailing list and vice
versa. Admins who leave/join the root group must be added/removed from the
list respectively.
- Elected Admins should also be on the elected-admins list. This address is
mainly used for mail to PayPal, user renewals, registration, and general administration tasks.
- It is the responsibility of the Elected Admins to ensure that all mailing lists (committee, helpdesk, webmaster, elected-admins, admins, etc) are all up-to-date.
After being elected it is your time to learn the ropes and become familiar with the technicalities of Redbrick.

### Admin Account Responsibilities

As an adminisitrator, your new local account has extra priviliges (namely being
in the root group). For this reason, you should not run _any_ untrusted or
unknown programs or scripts.

If you must, and source code is available you
should check it before running it. Compile your own versions of other user's
programs you use regularly. It is far too easy for other users to trojan your
account in this manner and get root.

Do not use passwordless ssh keys on any of your accounts. When using an
untrusted workstation (i.e. just about any PC in DCU!) always check for
keyloggers running on the local machine and never use any non system or non
personal copies of PuTTY/ssh - there's no way of knowing if they have been
trojaned.

### General Responsibilities

Look after and regularly monitor all systems, network, hardware and user
requests (ones that fall outside of helpdesk's realm, of course!).

Actively ensure system and network security. We can't police all user accounts
and activities, but basic system security is paramount! Keep uptodate with
bugtraq/securityfocus etc. Check system logs regularly, process listings,
network connections, disk usage, etc.

### Downtime

All downtime must be scheduled and notified to the members well in advance by
means of motd & _announce_. If it's really important, a mail to
announce-redbrick and socials post may be necessary.

All unexpected/unscheduled downtime (as a result of a crash or as an emergency
precaution) must be explained to the members as soon as possible after the
system is brought back. A post to announce, notice in motd or possibly a mail
to committee/admins is sufficient.

When performing a shutdown, start the shutdown 5 or 10 minutes in advance of the
scheduled shutdown time to give people a chance to logout. It may also be useful
to disable logins at this stage with a quick explanation in `/etc/nologin`.

### Documentation

Please read all the documentation before you do anything, but remember that the
docs aren't complete and are sometimes out of date. Please update them as you go
:D
Not alone of course! The previous Admins will assist you on this journey and be there to answer any of your questions, along with this documentation.

---

@@ -269,3 +184,118 @@ The IRC services run by Trinity for all the netsocs. The two services are
for more details.

---

## Redbrick System Administrator Policies

The purpose of this is to brief new Redbrick system administrators on
the current setup, policies and practices in place and to serve as the place to
record all such information for current and future administrators.

### Admin Account Priviliges

- By default, all admin accounts will remain the same as the rest of the
committee.
- Each admin will recieve a local account on each machine that will be
in the root group. This allows you to log on if ldap goes down.
- Accounts should
not be placed into any other 'system' or priviliged accounts (e.g. pgsql, mail,
news, etc.) but by all accounts (hah, bad pun!) can be placed into useful groups
(e.g. cvs, webgroup, helpdesk etc.)

### Root account

When su'ing to root, please observe the following:

- Wait for the password prompt before typing in the password! Sometimes
lag/terminal freezes or whatever can kick in. The other classic mistake is
typing the password in place of the username (say for a console login).
- Make sure LOGNAME is set to your unix name. The linux boxes will prompt you
for this. On OpenBSD you can use 'su -m' to keep the environment.
- Don't change the root account/finger information!
- If you wish to use another shell, place customisations in your own file. For
bash, `/root/.bash_profile.<USERNAME>` and for zsh `/root/.zshrc.<USERNAME>`.

`/root/.zshrc` and `/root/.bash_profile` source in the appropriate file as long
as `$LOGNAME` is set right (see above). Do not put personal customisations into
the default root account setup, remember other people have to use it.

Common aliases can be put in /root/.profile, familiarise yourself with the
existing ones, they can come in handy.

- Please keep `/root` tidy. Don't leave stuff strewn about
the place!
- Make sure to check permissions and ownership on files you work on
**constantly** especially files with important or sensitive information in
them (e.g. always use `cp -p` when copying stuff about).
- Only use root account when absolutely necessary. Many admin tasks can be done
or tested first as a regular user.

### Gotchas

Couple of things to look out for:

- `killall` command, never ever use it!
- Alias `cp`, `mv` & `rm` with the `-i` option.
- If you're ever unsure, don't! Ask another admin or check the docs.
- Always always double check commands before firing them off!

### Admin Mailing Lists

[lists.redbrick.dcu.ie](lists.redbrick.dcu.ie) (Postorius)

- All accounts in the root group must be on the admin mailing list and vice
versa. Admins who leave/join the root group must be added/removed from the
list respectively.
- Elected Admins should also be on the elected-admins list. This address is
mainly used for mail to PayPal, user renewals, registration, and general administration tasks.
- It is the responsibility of the Elected Admins to ensure that all mailing lists (committee, helpdesk, webmaster, elected-admins, admins, etc) are all up-to-date.

### Admin Account Responsibilities

As an adminisitrator, your new local account has extra priviliges (namely being
in the root group). For this reason, you should not run _any_ untrusted or
unknown programs or scripts.

If you must, and source code is available you
should check it before running it. Compile your own versions of other user's
programs you use regularly. It is far too easy for other users to trojan your
account in this manner and get root.

Do not use passwordless ssh keys on any of your accounts. When using an
untrusted workstation (i.e. just about any PC in DCU!) always check for
keyloggers running on the local machine and never use any non system or non
personal copies of PuTTY/ssh - there's no way of knowing if they have been
trojaned.

### General Responsibilities

Look after and regularly monitor all systems, network, hardware and user
requests (ones that fall outside of helpdesk's realm, of course!).

Actively ensure system and network security. We can't police all user accounts
and activities, but basic system security is paramount! Keep uptodate with
bugtraq/securityfocus etc. Check system logs regularly, process listings,
network connections, disk usage, etc.

### Downtime

All downtime must be scheduled and notified to the members well in advance by
means of motd & _announce_. If it's really important, a mail to
announce-redbrick and socials post may be necessary.

All unexpected/unscheduled downtime (as a result of a crash or as an emergency
precaution) must be explained to the members as soon as possible after the
system is brought back. A post to announce, notice in motd or possibly a mail
to committee/admins is sufficient.

When performing a shutdown, start the shutdown 5 or 10 minutes in advance of the
scheduled shutdown time to give people a chance to logout. It may also be useful
to disable logins at this stage with a quick explanation in `/etc/nologin`.

### Documentation

Please read all the documentation before you do anything, but remember that the
docs aren't complete and are sometimes out of date. Please update them as you go
:D

---

+ 13
- 17
mkdocs.yml View File

@@ -51,26 +51,22 @@ markdown_extensions:
permalink: true
- attr_list
- codehilite:
guess_lang: false
guess_lang: true
- pymdownx.critic
- pymdownx.highlight
- pymdownx.superfences

nav:
- Home: index.md
- cheatsheet.md
- Services:
- services/index.md
- Bind9: services/bind.md
- CodiMD: services/codimd.md
- Gitea: services/gitea.md
- Icecast: services/icecast.md
- IRC: services/irc.md
- NFS: services/nfs.md
- ZnapZend: services/znapzend.md
- hardware.md
- network.md
- web.md
- monitoring.md
- procedures.md
- postmortems.md
- scripts.md
- services/index.md
- Bind9: services/bind.md
- CodiMD: services/codimd.md
- Gitea: services/gitea.md
- Icecast: services/icecast.md
- IRC: services/irc.md
- NFS: services/nfs.md
- ZnapZend: services/znapzend.md
- cheatsheet.md
- api.md
- roadmap.md

Loading…
Cancel
Save