This page explains what a tool account is, how to create a tool account/tool, and how to add and remove maintainers. For one-time setup steps to get started with Toolforge, see the Toolforge quickstart.
Tools and tool accounts
The terms "tool", "tool account", and "project" have the same meaning in Toolforge; "tool accounts" and "tool" are often used interchangeably. The tool is the basic unit of deployment in Toolforge. Each tool is actually a tool account with resources, processes, and other components in a tool-specific namespace.
A tool account is a group account associated with a tool. A tool account can have one or more members or tool maintainers. You create a separate tool account for each new tool you develop on Toolforge. When you're invited to work on or help maintain a tool, you'll join an existing tool account. Tool accounts enable multiple maintainers to collaboratively manage the software source code, configuration, and jobs for that tool.
Each tool account includes:
- A home directory on shared storage:
- The ability to run a Web service which is visible at
- Database access credentials:
$HOME/replica.my.cnf, which provide access to the production database replicas as well as to project-local databases
- Access to the job and task queues
- Credentials and a namespace for running containers on the Kubernetes cluster
People who have access to a tool account are called maintainers. Maintainers have access to the tool account's code and data.
- Create tool accounts/tools
- Join existing tool accounts/tools
- Leave tool accounts/tools in the care of others
- Log in (sudo) to the tool accounts/tools
Join an existing tool account
All tool accounts hosted in Toolforge are listed on the tools list. Contact the maintainer to ask them if you can join an existing tool account. The maintainer can follow the instructions below to add you to that tool account.
Add or remove maintainers
Existing maintainers can follow these instructions to add new maintainers to a tool account:
- Log in to the Toolforge admin console.
- Navigate to the tool listing and select the tool you want to manage from the left sidebar.
- Click "Manage maintainers". Add the new maintainers and click "Update".
Create a new tool account / tool
To create a new tool, create a new tool account in toolsadmin:
- Go to https://toolsadmin.wikimedia.org/tools/.
- Click on the "Tools" tab.
- Click the "Create new tool" link at the bottom of the "Your tools" sidebar.
- Follow the instructions in the tool account creation form. Note the instructions below about Naming your tool.
- After you create the tool account, log off, then log back in to access the new tool account.
Note: If you only recently received access to the tools project, you may get an error about appropriate credentials. Log out and back in to fix the issue.
If you were logged in through ssh when you created the tool account, you must log off and log in again.
Name a tool account / tool
The tool account and tool have the same name. This name is included in the URL for the web service, if the tool has one. Make sure the name is appropriate and is spelled correctly.
Note: Do not prefix the tool name with
tools.. This will cause problems during account creation.
Rename a tool account / tool
Tools can't be renamed. You can create a new tool with a new name and copy the code over from the old tool.
Switch to / become a tool account
Whenever you log in to Toolforge, you first SSH to the bastion host, but then you must "become" the tool account you want to work on. Become your tool by using the
$ become <toolname>
You should see the command prompt change to:
Troubleshooting: no such tool
$ become <TOOL NAME>
become: no such tool '<TOOL NAME>'
- Wait a few minutes for the tool account creation to complete.
- Check that the spelling of the tool name is correct.
Troubleshooting: You are not a member of the group tools
$ become <TOOL NAME>
You are not a member of the group tools.<TOOL NAME>.
Any existing member of the tool's group can add you to that.
- If you are already logged in via SSH when you create a new tool, log out, and log in again to activate your new permissions.
Manage files in Toolforge
|This doc could be improved by moving this content to a new doc; see phab:T347753. Contributions welcome!
Toolforge is a shared environment, and by default all files you create will be public. This means that when you create files containing passwords or other secret information, you need to set correct file permissions to ensure it stays private. You can use the following command to create a new blank file that only you can read or edit:
$ install -m 600 /dev/null FILE_NAME
You can use
scp to copy files from your computer to Toolforge. To make files available to a tool account, copy or move them from your home directory to the tool's home directly:
yourshellaccountname@tools-sgebastion-10:~$ cp somefile ~tools.toolaccount/
Note that the tool account will have to
take ownership of the file before it can use it, see below.
Take ownership of files
take command allows you to change ownership of the file(s) and directories to the calling tool user.
The permissions of the file(s) before
take is run must include the tool user as either the owner or group. This prevents
take from being abused to take over arbitrary files.
To take ownership of files as your tool account:
becomeyour tool / tool account:
yourshellaccountname@tools-sgebastion-10:~$ become toolaccount tools.toolaccount@tools-sgebastion-10:~$
- As your tool/tool account,
takeownership of the files:
tools.toolaccount@tools-sgebastion-10:~$ take FILE
Mount your tools home directory onto your local machine
Modifying files on Toolforge servers may be difficult; after all, you are restricted to terminal-based editors. If you prefer to use modern IDEs such as Visual Studio Code, Eclipse, etc. you can mount the home directory of your tool onto your local Linux machine or virtual machine (VM).
First, create an empty directory on which you would mount the Toolforge remote directory. In the code examples below, it is assumed that you have created a local directory at
~/remote for this purpose.
To mount, use a command like this:
$ sshfs -o allow_other -o workaround=rename login.toolforge.org:/data/project/toolname ~/remote
allow_other option helps avoid permission issues, and the
workaround=rename option helps avoid issues with overwriting existing files.
You may receive a notice said:
fusermount3: option allow_other only allowed if 'user_allow_other' is set in /etc/fuse.conf; in such case, just uncomment line
user_allow_other in your
Remember to specify your Toolforge username if it's different from the one you have locally, i.e.
... firstname.lastname@example.org:/.... If it's wrong it will cause the generic error message:
read: Connection reset by peer
To unmount, use this command:
$ umount ~/remote
In certain situations, the above command may fail to work (e.g. network issues); if you need to forcefully unmount the network file system, you can use this command:
$ fusermount -zu ~/remote
Transferring files via rsync
Rsync is a good and fast way to copy and synchronize files. This example shows how to copy a directory to your Toolforge home directory. It also enforces permissions for everyone to read the copied files (common for a public_html).
$ rsync --delay-updates -F --compress --archive --no-owner --no-group --chmod=Du=rwx,Dog=rx,Fu=rw,Fgo=r yourLocalDirectory login.toolforge.org:/home/yourshellaccountname/destinationDirectory
- We do not try to preserve the local user and group as they likely don't match what is on the server anyway.
- You can add
--delete-afterto remove files from the destination if they are not present in the source. If you regularly sync the same directory but the filenames change (say a vendor or node_modules directory), this might be useful to avoid the destination dir from filling up with old unnecessary files.
In order to copy to the tool's home directory, you need to ensure that rsync becomes the tool user:
$ rsync --delay-updates -F --compress --archive --no-owner --no-group --rsh='/usr/bin/ssh -S none -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null' --rsync-path='sudo -u tools.toolaccount rsync' --chmod=Dug=rwx,Dg+s,Do=rx,Fug=rw,Fo=r yourLocalDirectory login.toolforge.org:/data/project/toolaccount/destinationDirectory
- the sudo to a different user
- forwarding the rsync on the remote server via local ssh/rsync
- the different destination path
- different permissions (we give the group write permissions in this example and we preserve the +s
Add a description to your tool account / tool
Each tool can provide a description by creating a toolinfo record using https://toolsadmin.wikimedia.org/tools/.
$HOME/.description system is deprecated and will stop providing any benefit at some point in the future.
Delete a tool account
Mark a tool for deletion by using the "Disable tool" button on the tool's detail page on https://toolsadmin.wikimedia.org/. Disabling a tool will immediately stop any running jobs including webservices and prevent maintainers from logging in as the tool. Disabled tools are archived and deleted after 40 days. Disabled tools can be re-enabled at any time prior to being archived and deleted.
Backup Toolforge data
There are no user-accessible backups in Toolforge.
You should use a source or version control tool to preserve your code and make regular backups of data. Learn more.
Communication and support
Support and administration of the WMCS resources is provided by the Wikimedia Foundation Cloud Services team and Wikimedia movement volunteers. Please reach out with questions and join the conversation: