This article applies to the Wheezy Raspbian official release of 15/7/2012.
raspi-config was introduced with the advent of the Debian Wheezy image. It helps you configure your Pi. It is a work in progress so the number of menu items and the ease of use of those items will increase with time. If anyone feels willing and able to improve raspi-config then please contact Alex Bradbury .
- 1 The raspi-config
- 2 Moving Around the Menu
- 3 What raspi-config does
- 4 INFO - Information About This Tool
- 5 Running raspi-config another time
- 6 Menu Options
- 6.1 EXPAND-ROOTFS - Expand Root Partition to Fill SD Card
- 6.2 OVERSCAN - Change Overscan
- 6.3 CONFIGURE-KEYBOARD - Set keyboard layout
- 6.4 CHANGE_PASS - Change password for ‘pi’ user
- 6.5 CHANGE_LOCALE - Set locale
- 6.6 CHANGE_TIMEZONE - Set timezone
- 6.7 MEMORY_SPLIT - Change memory split
- 6.8 SSH - Enable or disable ssh server
- 6.9 BOOT_BEHAVIOR - Start Desktop on Boot?
- 6.10 UPDATE - Try to upgrade raspi-config
- 6.11 <FINISH>
- 7 First-boot activity
- 8 References
When you start your Pi the display shows lots of scrolling text with a couple of pauses lasting in total a few tens of seconds. If starting for the first time using the Wheezy image, or when running raspi-config another time (see below), the raspi-config menu will then appear. It has the following entries:
info Information about this tool expand-rootfs Expand root partition to fill SD card overscan Change overscan configure-keyboard Set keyboard layout change_pass Change password for ‘pi’ user change_locale Set locale change_timezone Set timezone memory_split Change memory split ssh Enable or disable ssh server boot_behaviour Start desktop on boot? update Try to upgrade raspi-config <Select> <Finish>
Moving Around the Menu
At any point from within any of the menu or sub-menu options the Tab key will toggle about the selected entry and the options at the bottom inside angle brackets, cursor keys move up and down menus. There is an exception to this and that’s with the change_locale option, ignore that exception for now it’s covered later.
Some of the menu entries take quite a while to display. The user experience looks like its running a desktop but in fact it isn't; its using the command line and its graphics capabilities (remember VDU's?) so occasionally the screen will scroll a bit.
What raspi-config does
Some menu entries modify the file /boot/config.txt. This file, out of the box, contains a number of commented out configuration entries; raspi-config adds entries at the end of this file. You can see what raspi-config has done to the file by viewing it on the Pi using Leafpad and, if you really mess things up you can edit the file from the SD card using Notepad on a Windows PC. More information on editing config.txt here R-Pi_ConfigurationFile
Other entries modify Linux configuration files, some take effect immediately, others at the next boot.
INFO - Information About This Tool
This would be really helpful if it actually explained the options in the menu, hopefully at least it will provide a reference to this Wiki page.
It helpfully advises you may have difficulties if you have heavily customized your installation but as this is probably the first thing a rookie is going to see the likelihood of a heavily customized installation is small.
Running raspi-config another time
Following the first boot, your raspberry pi will boot into the command prompt or desktop (depending on your choice).
You can run it at any time after that by typing (case sensitive):
At the command line or in a terminal window. The sudo (do as superuser) is necessary because you will be changing files that you as user pi do not own, its Debian's way of providing a root login.
The lovely thing about the Pi is that, if you mess up, it will not be difficult to re-image.
EXPAND-ROOTFS - Expand Root Partition to Fill SD Card
This does what it says on the tin so if you have installed Wheezy on a 4GB or greater card use this option and AFTER REBOOT it will use all of the SD card. The Wheezy image takes nearly 2GB so if you are going to install additional software or large files its worth doing, however you don't need to do it on first boot. The downside of using all of a larger card is that it takes much longer to backup the image.
OVERSCAN - Change Overscan
What would you like to do with overscan <Disable> <Enable>
Any changes will take effect after a reboot. If you change a setting and end up losing the left side of the screen you can easily edit /boot/config.txt on a PC to undo the changes.
Televisions do not usually display the whole of the picture, they Overscan and crop off a few percent of the image. This is to hide the data signals such as teletext which use the outer lines of the picture (could be a hangover from analogue TV). Computers, including the Pi, use all the lines for real display so often the image displayed by computers on TV's is cropped.
To avoid losing the critical left column at first boot the clever Pi people have deliberately enabled Overscan and used positive Overscan vlauses to make the displayed image smaller, and to play safe much smaller. This means, depending on your monitor/TV, there may be black borders around the picture. LXDE will show the wrong resolution in its display information as it shows you the size of the framebuffer (display_size - overscan).
On some displays, particularly monitors, just disabling Overscan will make the picture fill the whole screen and correct the resolution. For other displays it may be necessary to leave overscan enabled and fiddle with Overscan values, more information here R-Pi_Troubleshooting#Big_black_borders_around_small_image_on_HD_monitors.
CONFIGURE-KEYBOARD - Set keyboard layout
Slow to display and, if you select some of the non-default options, there will be a short delay while changes are made. Changes take effect immediately except for changes to X-server exit which require a reboot.
This menu for using different attached keyboards. Brands of keyboards are chosen first followed by other choices to set up nationality of keyboards etc.
Default is Generic 105-key (Intl) PC. If you cannot find your keyboard on the list then use one of the generic keyboards but it’s probably not a big deal if you can't find yours on the list, have fun remember you can always, change it later or re-image if you're really stuck.
The next screen regards keyboard layout. If you are not using the first choice of English UK select Other and you will be faced with a long list of other national keyboards. Funnily enough this list includes English UK.
Next screen is quite well documented on the screen you're probably going to run with one of the top two choices. These are:
The default for the keyboard layout
No AltGr key
To be honest if this is your first setup and you get this wrong it’s not going to break the bank and as I keep saying if in doubt re-image and start again.
Next screen; well if your using a standard keyboard then you probably don’t have a compose key and if your new to computing as intended you're not likely to need one for a while so I would suggest choosing
No compose key
The next screen is a useful one and the on screen documentation is actually quite clear provided you know what is meant by “X server” so here’s an outline:
If you choose to boot to the command line (see later) then after login the Pi will tell you that you can run startx. Startx is the command to run the windows (like) screen where you use a mouse to select options.
This is the X server and to get back to command line (that’s all the typed stuff) you can use [Ctrl][Alt][Backspace] all pressed at the same time to shut down this X server screen; you can always restart it by typing “startx”. Always handy if you have a flaky mouse or are using a wireless mouse that eats batteries.
Of course this is pointless if you don’t remember the key combination when the time comes!
CHANGE_PASS - Change password for ‘pi’ user
The default user for the Wheezy install is pi and its password is raspberry. Until you're familiar with the setup it’s probably better to leave this password as it is at least till you are happy changing stuff. In addition you can re-run raspi-config to change it at any time.
If you screw this up be prepared to re-image and lose any work you have done and programs installed (you did back up your data didn't you). With Linux and Unix forgotten passwords are a killer the Raspberry Pi is one of the simpler systems. Let's face it till you know what your looking at, the out of the box solution of pi and raspberry are probably all you will need.
CHANGE_LOCALE - Set locale
Slow to start up and there will be a delay while locales are generated.
You can tell this was written by a computer engineer and not a human how about this as an alternative.
change_locale Tell the computer if you need non English characters.
Sheesh! a computer aimed at children and new users and then you expect them to know what locale means (Google's your friend?).
This menu option gives you a massive list of choices that look like they were written by one of the infinite monkeys of legend (goggle infinite monkeys Shakespeare if you don’t understand this reference).
The default setting is
en_GB UTF-8 UTF-8 (ain't it nice to have a UK produced computer!)
English, Great Britain and UTF-8 is a code related to showing all of the characters usually needed to show English letters and other symbols on the screen. If you are working in some other language than English then you will probably need to play around with this.
You can select multiple choices in the list the space bar toggles them on and off (this was the exception I mentioned earlier) and it’s a long list. Basically if you want to work in more than one language then you will need to make other choices from this list based on the languages you intend to use.
If you are working in English only the default choice is probably the only one you will need.
CHANGE_TIMEZONE - Set timezone
Slow to display.
This is where you setup your clock; now it’s no big issue if it’s wrong it just means the date and time assigned to files you create (automatically when you make them) will be out and its not hard to set this up. (What is the effect if you are not connected to the internet and don't have time set with ntp?)
The set up consists of two layers basically to make your selection easier to find.
First option screen think Continent; just to confuse things you have US and America because we all know USA is not part of America. Actually the US option just gives you a shorter list containing the US time zones that are included in the American list; they just made a shorter list under US for all those Good Old Boy American Citizens who don’t know about American places outside of the USA. (flames imminent!).
SystemV relies on you knowing what SystemV is (Think Unix and ignore it for now).
Most people know where they are in the world for time zone; for me it’s Europe then London on the next screen but I’ve always been of the opinion that there should be ropes and lights around the M25 with signs saying “Danger hole in the world Keep Out” but then I’m not from London and the M25 was always the road to hell.
MEMORY_SPLIT - Change memory split
This allows you to choose how much of the RAM memory is set aside for the Broadcom Graphics Processing Unit (Videocore) and how much for the operation of the main ARM processor.
Three choices 32MiB for Videocore, 64MiB for Videocore, 128MiB for Videocore. First time users should leave it at the default 64MiB for the Videocore. There is more information on when to use the different options here RPi_Advanced_Setup. You can change it with raspi-config and it will take effect at the next reboot (check).
Now let’s assume your really fresh to writing code, as in never done this before ever. You're not going to be writing really complex Artificial Intelligence type programs and your also unlikely to be running cutting edge real time first person shooter games not yet anyways. I like the idea of having 128 meg for graphics. As a new programmer your not likely to push graphics unless you want to do something with photos or live streaming (Watching Live TV on your Pi).
SSH - Enable or disable ssh server
This change takes effect when???
This option enables or disables the ssh server, a program which sits quietly in the Pi looking for ssh connections from other computers. The default setting is on and there's little reason for a new user to change this unless your home network has hostile users or is open to the Internet.
ssh means 'secure shell'. It is a communication protocol which will allow you to log into the Pi from another computer on your network using a program like Putty to provide a command line interface in a terminal window.
Putty is free and available to download. It’s free Open source and runs on both Windows and Linux. You actually don't need Putty on Linux and Mac, because you can use the built-in ssh client in the Linux and Mac terminals. Just open a terminal and type 'ssh ipAddress' (replacing ipAdress with the ip of your Raspberry Pi).
This option allows access to the Pi without a monitor attached to the Pi. OK it’s easier if you have one but let’s say you want to do some command line stuff and your partner/brother/sister whatever wants to use the TV for Corrie or suchlike. Its particularly useful for starting a VNC server on the Pi so you can use the Pi's desktop on another computer. More details here 
Using Putty or the like is pretty straightforward. You will need to know the IP address of the Pi, either by watching the startup output as it scrolls by, typing sudo ifconfig at the Pi's command line or terminal window, or looking at your router. The IP address is dynamic and can change, particularly if you have not used the Pi for a day or so.
However if you are using everything from the box as is. That is to say you have your HDMI connected to a TV and a Keyboard and Mouse on the Pi and you have the menu running then I suggest you could disable ssh just to be on the safe side security wise(note just a suggestion).
BOOT_BEHAVIOR - Start Desktop on Boot?
This gives you two modes of working:
DESKTOP When powered up the Pi will automatically log you in as pi user and display the desktop. Pressing the red Exit button on the right hand side of the screen will give the options to logout, shutdown or reboot. Logout returns to a login screen not to the command line. The command line is only accessible through a terminal window. The experience is very Windoze like, you may not need any linux commands ever, and its very quick to get to the desktop, its main downside being that since you are automatically logged in at power up there is no protection from hostile users in your household.
COMMAND LINE When powered up the Pi stays in the command line (the big black screen). After lots of scrolling text you will be asked for your username and password. If this is successful information about the last Login is displayed which is useful for finding out if it was you, your son/daughter/grandmother/cat that was the last to login and screw up your Pi.
Then you see the standard copyright and NO WARRANTY message the latter just legalese for “your doing this at your own risk” that kind of goes without saying.
Then the key line.
Type ‘startx’ to launch graphical session
So, if at this point you type startx followed by hitting the Enter key you will be launched headlong into a windows style environment. When you have finished work Logout using the red Exit button (bottom right). Since you started from the command line this menu has only the Logout option which takes you back to the command line. To halt you must type sudo halt or to reboot sudo reboot. For halting wait until 'System Halted' is displayed before pulling the plug.
If on the other hand you want to play in the rarefied atmosphere of the command line environs then type away. You are in the home directory of the pi user; typing ls followed by [enter] will display its files and directories. Directories are in blue so type cd python_games then ls to change folder and display its contents. When you have finished don't forget to type sudo halt and wait until 'System Halted' is displayed before pulling the plug.
UPDATE - Try to upgrade raspi-config
Unless there have been recommendations on the forum by someone from the core volunteer team to use this, don't.
We could get into the Catch 22 situation where a bug is introduced into raspi-config that stopped it working. This option runs the apt-get commands to update the raspi-config software from a remote repository. You will need to be connected to the internet to use it.
Use this when you have completed your changes. You will be asked whether you want to reboot or not. When used for the first time its best to reboot. This should restart your Pi. Scrolling text should appear immediately and there will be a pause if you have chosen to resize your SD card.
When a new image that contains the raspi-config utility is booted the first time, the session starts with the raspi-config screen. Use the help above when using the utility on first boot. This behaviour is driven by the raspi-config.sh script in the /etc/profile.d directory.
#!/bin/sh # Part of raspi-config http://github.com/asb/raspi-config # # See LICENSE file for copyright and license details # Should be installed to /etc/profile.d/raspi-config.sh to force raspi-config # to run at initial login # You may also want to set automatic login in /etc/inittab on tty1 by adding a # line such as: # 1:2345:respawn:/bin/login -f root tty1 </dev/tty1 >/dev/tty1 2>&1 # RPICFG_TO_DISABLE if [ $(id -u) -ne 0 ]; then printf "\nNOTICE: the software on this Raspberry Pi has not been fully configured. Please run 'sudo raspi-config'\n\n" else raspi-config exec login -f pi fi
This runs the raspi-config script (found as /usr/bin/raspi-config). When that has completed, the script above shows the login prompt for the pi user.
When the raspi-config script runs, and the user selects the Finish option, the script above is deleted so that it will not run again. When the Raspberry Pi is first booted it uses the /etc/inittab script, which does an automatic login as root. The Finish option of the raspi-config script modifies part of the inittab script, from the login as root:
... # 1:2345:respawn:/sbin/getty --noclear 38400 tty1 # RPICFG_TO_ENABLE 1:2345:respawn:/bin/login -f root tty1 </dev/tty1 >/dev/tty1 2>&1 # RPICFG_TO_DISABLE 2:23:respawn:/sbin/getty 38400 tty2 3:23:respawn:/sbin/getty 38400 tty3 ...
to the standard login action:
... 1:2345:respawn:/sbin/getty --noclear 38400 tty1 2:23:respawn:/sbin/getty 38400 tty2 3:23:respawn:/sbin/getty 38400 tty3 ...
Is this useful?
This may be just a bit of background information, but it could be useful if you wish to distribute your own SD cards to friends, based on your own configuration. You may have added or removed packages, changed configurations, or any number of things that you and your friends think are useful.
You can create a backup image of your SD card, but that image will not execute the raspi-config script on first boot; your friends may need to run it because they have different hardware. To make that script run automatically, copy the top script to /etc/profile.d/raspi-config.sh and change the /etc/inittab script back to the original lines.