Table of Contents

SSH/Xterm and Common Commands

The recommended way to access Batocera's terminal is through SSH from another computer on the same local network (so that you get nice features like command history and ASCII coloration). First, make sure that SSH is enabled on your Batocera machine (it is enabled by default): check /userdata/system/batocera.conf and make sure system.ssh.enabled=1 (with no leading #) is present. Then use your preferred SSH tool to connect; enter ssh root@batocera or equivalent in your terminal (or the Command Prompt on Windows 10+).

Windows users are advised to use PuTTY or KiTTY to connect via SSH.

The username is root. This is the only user on a Batocera machine. So, the typical address to attempt an SSH connection to the Batocera machine would be root@batocera.local or just root@batocera. If none of those work, you can connect to root@192.168.###.###, where 192.168.###.### would be the IP address that you get from MAIN MENU → NETWORK SETTINGS in the Batocera interface.

For example, this is how PuTTY should look when SSH'ing in:

Click “Save” after everything is set up to create a double-clickable profile for convenience.

Once in the SSH session, enter the password. The default password is linux. While typing the password, no asterisks will appear. That is how Linux does things.

If you do not want guest access, turn on “Enforce Security” from MAIN MENU > SYSTEM SETTINGS > SECURITY and specify a password.

Turning on ENFORCE SECURITY will also require your username and password to access the network share as well. Despite this, keep in mind that Batocera is not a secure operating system and exposing it to a public network is at your own risk.

A successful login via SSH looks similar to this:

This is referred to as ASCII art.

A local terminal can also be accessed on the Batocera machine itself by opening xterm from the Applications menu in the file manager ([F1] on the system list), however this can only be done on platforms which support the Xorg backend (such as x86_64).

It is also possible to open a new TTY session from anywhere in Batocera by pressing [Ctrl]+[Alt]+[F5] (you will be asked to login, refer to above). To return to Batocera after doing this, press [Ctrl]+[Alt]+[F2]. In Batocera v31 and lower, this shortcut is [Ctrl]+[Alt]+[F3]. In Batocera v31 and lower, it is not recommended to use this terminal due to garbled text input; only use it in emergency situations.

Whenever using the command line, try to understand what the commands are doing exactly. Even if it doesn't seem like it, certain commands can be used in harmful ways. For example, putting simply > empty.txt without any command will create an empty file called empty.txt in the current working directory. That's fine, right? If you already had a useful file with this name, it'll be empty after this command.

Even more dangerously, a short command like rm -rf / or :(){:|:&};: could destroy your entire hard drive without prompt!

Copy and paste work differently in PuTTY than in many other Windows programs. For a general introduction to PuTTY features including copy and paste, refer to the PuTTY documentation.

Password-less authentication

From a remote machine to Batocera

Batocera can remember the SSH client's key such that it no longer requires a password to type in.

This section assumes that your Batocera user data partition is formatted Linux-native (ext4 by default, or btrfs). The chmod commands below won’t be applied correctly on FAT32 or NTFS partitions, and as a result passwordless SSH will fail.

  1. On Batocera, run the following in terminal: 
    chown root:root / /userdata/ /userdata/system/
chmod 755 / /userdata/ /userdata/system/
mkdir -p ~/.ssh
touch ~/.ssh/authorized_keys
chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys
  2. On the client computer (the one which logs into Batocera via SSH), generate its SSH keypairs (if not already done so) and add the public Batocera SSH key to the Batocera SSH configuration as follows:
    • For most Linux-based distributions, run the following: 
      ssh-keygen

      and mash [Enter] through all of the questions. Don't worry about setting a master password for the public keys. Then run: 

      cat ~/.ssh/id_rsa.pub | ssh root@batocera.local 'cat >> /userdata/system/.ssh/authorized_keys'

      replacing batocera.local with the IP address of Batocera if using a static IP.

    • For Windows, paste the id_rsa.pub key from C:\<yourUsername>\.ssh\id_rsa.pub into Batocera at ~/.ssh/authorized_keys.

That's it. You should be able now to SSH into your Batocera system from your SSH client without entering any password.

Advanced users may be tempted to use ssh-copy-id to set up the authorized_keys file. This will not work, due to limitations in the Dropbear setup as implemented in Batocera.

From Batocera to a remote machine

It is also possible to set up passwordless authentication the other way around: From Batocera to am remote machine. Since Batocera does use the Dropbear SSH service, the ssh-keygen command will not work to create a local SSH keypair. Instead, the following command will generate the according SSH keypairs:
dropbearkey -t rsa -f ~/.ssh/id_dropbear
Once done, the public SSH key will be shown on the command line window. In case you want to show the public SSH key later, do so by executing:
dropbearkey -y -f /userdata/system/.ssh/id_dropbear | grep '^ssh-rsa' > /userdata/system/.ssh/id_dropbear.pub

You can now copy the according public SSH key to your remote machine as already shown above, but the other way around of course.

Basic SSH commands

Once you are connected to Batocera, you can use most standard Unix commands.

When we say most, we mean mostly the GNU coreutils. Batocera is a lean build-root Linux based system, which does not have a lot of the commands or packages that other distributions typically do. A lot of commands aimed at Ubuntu or Mint for example won't work here.

Some command-line tools have an --help option describing how to use the program, for example, typing cp --help will print how the command is used in the command-line interface. 

BusyBox v1.31.1 (2020-11-28 14:11:54 CET) multi-call binary.

Usage: cp [OPTIONS] SOURCE... DEST

Copy SOURCE(s) to DEST

	-a	Same as -dpR
	-R,-r	Recurse
	-d,-P	Preserve symlinks (default if -R)
	-L	Follow all symlinks
	-H	Follow symlinks on command line
	-p	Preserve file attributes if possible
	-f	Overwrite
	-i	Prompt before overwrite
	-l,-s	Create (sym)links
	-T	Treat DEST as a normal file
	-u	Copy only newer files

Most command-line tools have a syntax similar to <program> -<option flags> <parameters of program> <path/to/input/file> <path/to/output/file>, but not all of them. It's worth reading their manual before using them.

The default working directory is the HOME folder of Batocera at /userdata/system. This will appear as ~ in your terminal. You can check what directory you are currently in with pwd.

Using the command line with paths of files can be confusing at first, there are two types of paths:

If a path, or a filename, contains special characters or spaces, you will need to put either single quotes ' or double quotes " around it.

Most commands can be immediately halted with [Ctrl]+[C]. Note that doing this may corrupt data if that program is in the middle of editing a file.

But if [Ctrl]+[C] is used, then how do you copy text from a SSH session? Simple: highlight the text and it will automatically be copied to your host system's clipboard. To paste, right click.

Basic file usage

Batocera includes a powerful orthodox file manager called Midnight commander:

Files can also be manipulated using standard Unix commands. Here is a cheat-sheet:

Batocera store

The content downloader, essentially. This was introduced in Batocera v29 (FIXME or close enough to it).

Debugging

Most of these commands require export DISPLAY=:0.0 to be run first before they can work.

The following commands can be used to debug your Linux-based operating system:

How to install btop on Batocera v33 and earlier
BPYTOP is a more sophisticated system resource monitor powered by Python.

Starting with Batocera v34, an equivalent of bpytop is available for everyone, by simply entering btop from the command line (or btop --utf-force if your current locale doesn't support UTF-8). For versions prior to Batocera v34, follow the install guide below.

To install it: 

python -m ensurepip --upgrade
pip3 install bpytop --upgrade
batocera-save-overlay

This needs to be done every update.

Unique to Batocera:

Batocera resolution

Most of these commands require export DISPLAY=:0.0 to be run first before they can work.

Batocera ES swissknife (dev tools)

Batocera features some tools to aid developers. Run batocera-es-swissknife [FLAG] to use them. You can run batocera-es-swissknife --help to see the current list of flags, but here is a copy of that (last updated Batocera v32): 

  --restart  will RESTART EmulationStation only
  --kodi     will startup KODI Media Center stopping ES
  --reboot   will REBOOT whole system
  --shutdown will SHUTDOWN whole system
  --emukill  will exit any running EMULATORS
  --espid    checks if EmulationStation is currently active
      This number is the real PID of the binary!
      If the ouput is 0, then ES isn't active
  --emupid   to check if an Emulator is running
      This number is just the PID of emulatorlauncher.py
      If output is 0 then there is no emulator active!

  --arch     Shows current architecture running
  --version  Shows current version of BATOCERA running
  --update   Shows possible update for your install
      default: stable, you can type --update butterfly

  --overlay  will try to backup your overlay file
  --remount  toggle write access to <dir>, default /boot
      This switch can have serious effects for your setup
  --reset-ra will set all RA settings to default

Formatting tools

VERY DANGEROUS

SMART drive health check

This can check the S.M.A.R.T. health as reported by the drive. If looking for a basic guide on how to use these: https://linuxconfig.org/how-to-check-an-hard-drive-health-from-the-command-line-using-smartctl and https://www.techrepublic.com/article/how-to-check-ssd-health-in-linux/ (skip over the installation part, it's already included in Batocera since v34). More rigorous documentation can be found on the Arch Wiki's page about the tool.

Exercise restraint when testing your disks.

Internet functionalities

Logging to a file

Sometimes, you might prefer having the output of a command inside a separated text file instead of reading through the command line interface. to do that you can use the > and >> symbols followed by the path of a filename.

for exemple, the command ls gives you the list of all files and folders in your current working directory, if you want to gather this inside a text file named list-files.txt at /userdata/system, you simply need to use:

You can also pipe the output to another program by using the vertical line character (|). For example, dmesg | less will let you see a scrollable list of the output with the [Up]/[Down] arrow keys; dmesg | more will let you see a full page of the output at a time, moving forward with [Spacebar]. Both of these examples can be quit by pressing [Q].

Miscellaneous scripts

Custom aliases

While not mandatory, it is good to know you can create aliases of commands, they let you launch a command with a simple keyword. One way to do this can be done by creating a text file in /userdata/system, that file must be named .profile : it will contain aliases commands and will execute them when Batocera is launched, so be careful of what you do.

The alias command syntax is as follow:

alias customname='du -sh /userdata/system/batocera.conf'

In this example, once batocera has been restarted, entering customname in the command line will do the same as entering du -sh /userdata/system/batocera.conf (in this example, it basically returns the size of the batocera.conf file in the command-line interface)

A more useful, yet complicated example, would be to try and use ffmpeg to save a screenshot of Batocera in the screenshots folder for x86_64 devices, as devices other than Raspberry Pi's don't have an equivalent of raspi2png. In this example I call the custom alias “pc2jpeg”.

alias pc2jpeg='ffmpeg -hide_banner -loglevel error -f x11grab -i :0.0 -frames:v 1 /userdata/screenshots/$(date +%y-%m-%d_%H-%M-%S).jpg'

This commands does the following :

So by using the pc2jpeg custom command, a JPEG file will be created with a filename based off the date of the screenshot.

This functionality has since been integrated into the command batocera-screenshot. This example remains here to show you the syntax of alias.

Troubleshooting

Visit the relevant section in the troubleshooting page for further help.