From 0f6dce02f2060889c60c02dd442f54aa8782aaff Mon Sep 17 00:00:00 2001 From: Andi Chang Date: Sun, 20 Sep 2026 13:28:49 -0700 Subject: [PATCH] Add commands page --- .../infrastructure/nix-hosts/login-servers.md | 4 +- docs/user-docs/docs/policies.md | 4 +- docs/user-docs/services/account/index.md | 2 +- docs/user-docs/services/lab/printing.md | 2 +- docs/user-docs/services/mail.md | 2 +- docs/user-docs/services/mysql.md | 2 +- docs/user-docs/services/shell/commands.md | 38 +++++++++++++++++++ .../services/{shell.md => shell/index.md} | 2 +- docs/user-docs/services/web/backups.md | 2 +- docs/user-docs/services/web/index.md | 6 +-- docs/user-docs/services/web/jekyll.md | 2 +- docs/user-docs/services/web/wordpress.md | 2 +- mkdocs.yml | 2 +- 13 files changed, 54 insertions(+), 16 deletions(-) create mode 100644 docs/user-docs/services/shell/commands.md rename docs/user-docs/services/{shell.md => shell/index.md} (98%) diff --git a/docs/staff-docs/infrastructure/nix-hosts/login-servers.md b/docs/staff-docs/infrastructure/nix-hosts/login-servers.md index 5aa57b7..c8437ca 100644 --- a/docs/staff-docs/infrastructure/nix-hosts/login-servers.md +++ b/docs/staff-docs/infrastructure/nix-hosts/login-servers.md @@ -10,7 +10,7 @@ When contributing to the OCF codebase, you will need some way of running and testing your code. Most of our applications cannot be run on a personal machine--they need to be run on OCF infrastructure. For most projects we recommend doing all development from `koi`, a server available to all -staff. Our [Kubernetes server](../infrastructure/kubernetes/index.md) is also +staff. Our [Kubernetes server](../kubernetes/index.md) is also accessible from `koi`. ## Before you begin @@ -25,7 +25,7 @@ To log in, open a terminal window and type in: ssh username@koi.ocf.berkeley.edu ``` -For more instructions, see the [SSH docs](../../user-docs/services/shell/index.md). You should +For more instructions, see the [SSH docs](../../../user-docs/services/shell/index.md). You should replace `ssh.ocf.berkeley.edu` with `koi.ocf.berkeley.edu`. ## Setting up SSH Keys diff --git a/docs/user-docs/docs/policies.md b/docs/user-docs/docs/policies.md index a82c809..cc80316 100644 --- a/docs/user-docs/docs/policies.md +++ b/docs/user-docs/docs/policies.md @@ -14,8 +14,8 @@ These are the current policies of the Open Computing Facility: * The printing quotas as documented on the [Printing](../services/lab/printing.md) page * [Database policy](../services/mysql.md#policies) - * [Disk quota policy](../services/shell.md#disk-quotas) - * [Unattended processes policy](../services/shell.md#unattended-processes) + * [Disk quota policy](../services/shell/index.md#disk-quotas) + * [Unattended processes policy](../services/shell/index.md#unattended-processes) * [Virtual hosting policy](../services/vhost/index.md#policies) There are also OCF policies which apply only to staff. These policies can diff --git a/docs/user-docs/services/account/index.md b/docs/user-docs/services/account/index.md index 53a1437..5497e9d 100644 --- a/docs/user-docs/services/account/index.md +++ b/docs/user-docs/services/account/index.md @@ -40,7 +40,7 @@ signatory for the group. If your group isn't registered with the LEAD Center You can change your password over SSH if you know your current password. -Use [SSH](../shell.md) to run the command `passwd` and follow the +Use [SSH](../shell/index.md) to run the command `passwd` and follow the prompts as shown below. No text will appear when you are entering in a password, just press enter when done after each prompt. diff --git a/docs/user-docs/services/lab/printing.md b/docs/user-docs/services/lab/printing.md index 409fcb2..3c3f676 100644 --- a/docs/user-docs/services/lab/printing.md +++ b/docs/user-docs/services/lab/printing.md @@ -21,7 +21,7 @@ Please note: ## Remaining quota To see how many pages you have left for the day and semester, check your [OCF account](https://www.ocf.berkeley.edu/account/info/) online or run the `paper` -command [in the shell](../shell.md). Print +command [in the shell](../shell/index.md). Print quota is also displayed at the top of the screen when using a lab computer. Check your print balance regularly! diff --git a/docs/user-docs/services/mail.md b/docs/user-docs/services/mail.md index 8ba6d68..18099fe 100644 --- a/docs/user-docs/services/mail.md +++ b/docs/user-docs/services/mail.md @@ -6,7 +6,7 @@ Email sent to your username @ocf.berkeley.edu (e.g. `username@ocf.berkeley.edu`) will be forwarded to a contact email address of your choosing. -To configure a forwarding address, log in via [SSH](shell.md) and +To configure a forwarding address, log in via [SSH](shell/index.md) and enter the `update-email` command to view or update your contact email address. Note that you are required to keep your contact address up-to-date for as long diff --git a/docs/user-docs/services/mysql.md b/docs/user-docs/services/mysql.md index 578b47c..cef2412 100644 --- a/docs/user-docs/services/mysql.md +++ b/docs/user-docs/services/mysql.md @@ -30,7 +30,7 @@ If you are looking for a familiar phpMyAdmin interface, visit ## Creating a MySQL database -Log into the OCF via [SSH](shell.md), at the terminal prompt enter +Log into the OCF via [SSH](shell/index.md), at the terminal prompt enter the command `makemysql`. Hit yes to confirm the operation. Note your password in a safe place. diff --git a/docs/user-docs/services/shell/commands.md b/docs/user-docs/services/shell/commands.md new file mode 100644 index 0000000..62c9616 --- /dev/null +++ b/docs/user-docs/services/shell/commands.md @@ -0,0 +1,38 @@ +--- +title: Commands +--- + +This is a brief guide to commands that can be run to manage your account, edit a website, or work on our server. To use them, access our login server via [SSH](index.md), either locally or on our [web terminal](https://ssh.ocf.berkeley.edu). Simply type in a command and hit enter to run it. To log out, run the command `exit`. + +In the tables below, `ARGUMENT` is a required argument and `[optional]` is an +optional one. For more information on a specific command, run `man COMMAND`. + +## OCF commands + +These commands help you manage your OCF account. + +| Command | Description | +|---------|-------------| +| `how SCRIPT` | Shows the source code for a script | +| [`makehttp`](../web/index.md#via-ssh) | Puts a shortcut to your web directory in your home folder | +| [`makemysql-real`](../mysql.md#creating-a-mysql-database) | Generates a new random password for your database, creating the database if it does not exist | +| `paper` | Shows how many pages you can currently print | +| `update-email` | Prompts you to set a contact email address for your OCF account | + +## File commands + +For convenience, here is a very basic listing of commands to manage files. For +a more complete listing, see for example +[Wikipedia](https://en.wikipedia.org/wiki/List_of_Unix_commands). + +| Command | Description | +|---------|-------------| +| `cd DIRECTORY` | Changes the current directory to a new one | +| `cp [-r] SOURCE DEST` | Copies a file. The `-r` option allows for copying directories. | +| `less FILE` | Lets you view the contents of a text file | +| `ls [FILE]` | Lists information about files and directories | +| `mkdir DIRECTORY` | Creates a new directory | +| `micro FILE` | Lets you edit a text file with a basic interface | +| `mv SOURCE DEST` | Moves or renames a file or folder | +| `rm [-r] FILE` | Deletes a file. The `-r` option allows for deleting non-empty directories. | +| `rmdir DIRECTORY` | Deletes an empty directory. Safer than `rm -r`. | diff --git a/docs/user-docs/services/shell.md b/docs/user-docs/services/shell/index.md similarity index 98% rename from docs/user-docs/services/shell.md rename to docs/user-docs/services/shell/index.md index 375698e..8375052 100644 --- a/docs/user-docs/services/shell.md +++ b/docs/user-docs/services/shell/index.md @@ -104,4 +104,4 @@ If you're trying to run a webapp or other kind of server process on the SSH login server (`ssh.ocf.berkeley.edu`), please note that the SSH login server is firewalled and what you're trying to do unfortunately won't work. If you're a group and you're trying to run a webapp, you may want to consider -[apphosting](webapps/index.md) instead. +[apphosting](../webapps/index.md) instead. diff --git a/docs/user-docs/services/web/backups.md b/docs/user-docs/services/web/backups.md index 27947c2..36aa804 100644 --- a/docs/user-docs/services/web/backups.md +++ b/docs/user-docs/services/web/backups.md @@ -11,7 +11,7 @@ find you need a backup history of your own when you need to: * Regress to a previous state due to a bug * Recover from a security breach -You can make easy-to-restore backups over [SSH](../shell.md) by +You can make easy-to-restore backups over [SSH](../shell/index.md) by following the examples on this page. You could alternatively use SFTP, but this wouldn't allow you to back up a database. diff --git a/docs/user-docs/services/web/index.md b/docs/user-docs/services/web/index.md index e8d64a3..36e98b1 100644 --- a/docs/user-docs/services/web/index.md +++ b/docs/user-docs/services/web/index.md @@ -14,14 +14,14 @@ Groups, faculty, and staff may also request a [virtual host](../vhost/index.md) ## Uploading Files Upload files to your web space the same way you [upload files to your OCF -account](../shell.md) (typically SFTP if used remotely). The only +account](../shell/index.md) (typically SFTP if used remotely). The only difference is that files for your web space are placed in your `public_html` directory. ## Additional details The web server runs Apache 2.4 with FastCGI (mod_fcgid) and suEXEC. -Access and error logs are accessible in `var/log/apache2/vhost_error.log` at death@ocf.berkeley.edu using [SSH](../shell.md). +Access and error logs are accessible in `var/log/apache2/vhost_error.log` at death@ocf.berkeley.edu using [SSH](../shell/index.md). The web server itself runs as a dedicated user. If your .htaccess file is not world-readable (e.g., `chmod 644`), the web server will return the error "401 @@ -75,7 +75,7 @@ Here are two easy ways to re-create the symlink: #### via SSH -1. Login to your account via [SSH](../shell.md). +1. Login to your account via [SSH](../shell/index.md). 2. After you go past all system messages, you will see a command prompt: user@carp:~$ diff --git a/docs/user-docs/services/web/jekyll.md b/docs/user-docs/services/web/jekyll.md index f769805..6e37b91 100644 --- a/docs/user-docs/services/web/jekyll.md +++ b/docs/user-docs/services/web/jekyll.md @@ -9,7 +9,7 @@ static, it makes for very fast and simple websites. ## Set up your site 1. Go to either our [web-based SSH client](https://ssh.ocf.berkeley.edu/) or a - terminal (using [SSH](../shell.md) to connect to + terminal (using [SSH](../shell/index.md) to connect to `ssh.ocf.berkeley.edu`) and sign in with your OCF username and password. 2. Create a new directory for your Jekyll project and name it whatever you diff --git a/docs/user-docs/services/web/wordpress.md b/docs/user-docs/services/web/wordpress.md index 0926a71..d2d2799 100644 --- a/docs/user-docs/services/web/wordpress.md +++ b/docs/user-docs/services/web/wordpress.md @@ -13,7 +13,7 @@ during staff hours](https://ocf.io/staffhours) for in-person assistance. ## Installing WordPress -The easiest way to set up WordPress is via [SSH](../shell.md). Some +The easiest way to set up WordPress is via [SSH](../shell/index.md). Some simple instructions: 1. Go to our [web-based SSH client](https://ssh.ocf.berkeley.edu/) and sign in diff --git a/mkdocs.yml b/mkdocs.yml index c38d30f..cce7b4b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -47,7 +47,7 @@ extra_css: - stylesheets/extra.css markdown_extensions: - toc: - permalink: true + permalink: "ยง" - pymdownx.tilde - pymdownx.highlight: anchor_linenums: true