←	Sep 2013	→
S	M	T	W	T	F	S
1	2	3	4 Navigating on-system documentation	5	6	7
8	9	10	11	12 Basics of SSH	13	14
15	16	17	18 Basic shell tools	19	20	21
22	23	24	25 Introduction to IRC	26	27	28
29	30

Daniel Silverstone

There is a lot of on-system documentation available in a typical GNU/Linux (or similar) system. These range from the built-in help in tools, to manual pages, texinfo pages, examples and other packaged documentation in various forms. Knowing how to navigate these troves of information will help you immensely when you are looking for help on a particular part of your system.

Built in help

Most tools will have built in help which will, at least, give you an idea of the commandline syntax for using them. The standard way for tools to offer this to you these days is with a --help or -h commandline argument.

For example:

$ who --help
Usage: who [OPTION]... [ FILE | ARG1 ARG2 ]
Print information about users who are currently logged in.

-a, --all         same as -b -d --login -p -r -t -T -u
-b, --boot        time of last system boot
...

Commands which have been grandfathered in from a time before GNU long options were common may require the -h option form:

$ reset --help
reset: invalid option -- '-'
Usage: tset [options] [terminal]
...

Often this is good enough to get you the help, but sometimes it'll really be confusing. Some commands don't support -h or --help (or they end up mapping them to real arguments) and so you need to do something outlandish to get them to give up their hoarded secrets:

$ ssh-keygen -\?
ssh-keygen: illegal option -- ?
usage: ssh-keygen [options]
Options:
  -A          Generate non-existent host keys for all key types.
  -a trials   Number of trials for screening DH-GEX moduli.
...

Every now and again, a command has sub-commands (for example git, svn or morph) and for those there may be a help subcommand to help you along. For example:

$ svn help ls
list (ls): List directory entries in the repository.
usage: list [TARGET[@REV]...]

  List each TARGET file and the contents of each TARGET directory as
  they exist in the repository.  If TARGET is a working copy path, the
...

Give it a go, explore what commands can tell you about their usage and see what you can learn in only a few minutes.

Manual Pages

Most commandline applications, and indeed many non-commandline apps have manual pages. Manual pages are an old concept and as such they are often well provided for. Unfortunately they are also often written in a special language known as Mannish which can take a while to get used to.

The man command is your primary gateway to the manual pages on your computer. There is also apropos or man -k which can be used to search for appropriate pages to display. Manual pages are usually rendered for your terminal width at the point you invoke the man tool and will be displayed in the pager for you to scroll up and down at will.

$ man ls
... the manual page for ls is displayed ...

$ apropos revision
darcs (1)            - an advanced revision control system
git-blame (1)        - Show what revision and author last modified each line of a file
gitrevisions (7)     - specifying revisions and ranges for git
uupdate (1)          - upgrade a source code package from an upstream revision

Whenever manual pages (or indices) refer to other manual pages, they will tend to state not only the name but the section where that page can be found. That is the number in parentheses following the manual page names in the listing above. Traditionally the manual sections have specific meanings...

1: Executable programs or shell commands
2: System calls (functions provided by the kernel)
3: Library calls (functions within program libraries)
4: Special files (usually found in /dev)
5: File formats and conventions eg /etc/passwd
6: Games
7: Miscellaneous (including macro packages and conventions), e.g. man(7), groff(7)
8: System administration commands (usually only for root)
9: Kernel routines [Non standard]

You will also find unusual manual sections such as 3pm for Perl modules.

If you find that a given name for a manual page is available in multiple sections then you can select which section simply by running man section page. For example, the passwd program has a manpage, as does the passwd file format:

$ man passwd
... passwd(1) is shown...

$ man 5 passwd
... passwd(5) is shown...

Texinfo

GNU introduced a mechanism of offering documentation which was more powerful, hyperlinked and theoretically easier for the author to produce than manual pages. This is the texinfo or info system. Documentation in this form is often referred to as a Texinfo manual and the info program gives you access to it.

Sometimes manual pages will refer you to a Texinfo manual for further information about the topic you are investigating. For example:

$ man ls
...
       The  full  documentation for ls is maintained as a Texinfo manual.
       If the info and ls programs are properly installed at  your  site,
       the command

              info coreutils 'ls invocation'

       should give you access to the complete manual.

The example given (info coreutils 'ls invocation') shows how you can use the info tool to jump to a particular node (ls invocation) in the manual for coreutils.

Navigating in the info tool is pretty simple. You can use the arrow keys to move around the document. Anything with a double colon (::) after it is a link and you can press ENTER when your cursor is over such a link to traverse it. There are also a number of single keypress navigation options:

SPACE: Page down
b: Go up a page
n: Go to the next node
p: Go to the previous node
q: Quit the viewer

But perhaps the most important keypress to learn is h which will show you the help for the info viewer.

Packaged help and examples

This is the least well structured of the options available on a typical system. There is no standard way for examples etc to be provided. I shall limit myself to where you can look on Debian and derived systems such as Ubuntu or Linux Mint.

On these systems, each package which is installed places additional documentation in two common places. The first is simply a second package typically called whateverpackage-doc. For example, there is libvdk2-2c2 and its associated libvdk2-dev and libvdk2-doc packages. To get these packages onto your system, simply install them as you would any other.

Whatever package you are interested in, be it a -doc package or not, you can ask dpkg for the list of files in it with dpkg -L packagename and if you pipe that through grep doc then you'll get a good idea of where documentation can be found.

$ dpkg -L subversion | grep doc
/usr/share/doc
/usr/share/doc/subversion
/usr/share/doc/subversion/NEWS.Debian.gz
/usr/share/doc/subversion/copyright
/usr/share/doc/subversion/HACKING
/usr/share/doc/subversion/changelog.gz
...

As you can see, each package will also install a /usr/share/doc/<packagename> directory into which various documentation may be placed. This is a common place to find examples.

$ dpkg -L gnupg | grep example
/usr/share/doc/gnupg/examples
/usr/share/doc/gnupg/examples/convert-from-106

There's clearly many other places where documentation might lurk. Some of it might show in things like the GNOME documentation index displayed if you run gnome-help. Simply examine the contents of packages to see where they might be hiding documentation and you'll rapidly find it.

Conclusion

There is a significant amount of documentation available on your typical GNU/Linux (or similar) system. There's often no need to go to Google to find what you need to know. Just learn how to navigate what you already have.

Posted Wed Sep 4 12:24:31 2013 Tags: documentation shell

Lars Wirzenius

ssh, or the secure shell, is one of the essential tools for free software developers, system administrators, and anyone else who needs to get to the command line on remote computers. It forms an encrypted communications channel between two hosts, and allows you to do things across that secure channel:

Log into the remote end, to get a command line. You can then use that as if you were using a command line in a terminal window on your local machine.
Run X11 programs on the remote end, and have them open windows on your screen.
Transfer files using SFTP, an FTP-like file transfer protocol, except not broken and horrible. If you use a Linux desktop, your file manager can probably talk SFTP directly.
Forward local ports to the remote end, or the other way around. This can allow you to for example make a server on your laptop available to others on the Internet, or work around a firewall, sort of like a simple VPN.

Examples

If you have ssh installed on your machine, and listening to the localhost interface, try these commands:

ssh localhost
ssh localhost ls -l
ssh localhost -X xterm

The first form gives you an interactive shell on the remote machine, or in this case on your own machine. Normally, you'd connect to another machine instead of localhost, such as your VPS if you have one. Second form executs the command directly and then exits. The third form runs an X11 program on the remote end, but opens its window on your own desktop. All of these work as well (though perhaps more slowly) over the Internet as over localhost.

You can copy files using either the scp or sftp programs. For simple copies, scp is easy:

scp index.html your.server:public_html/

sftp can also be used directly from the command line, in addition to interactively, for fetching files:

sftp your.server:public_html/index.html

For more complicated transfers, and for uploading files, use sftp interactively.

Security

ssh is meant to be secure. Apart from encrypting the connection, it also verifies the server's host key, to help you feel confident you've connected to the right server.

The user can authenticate itself to the server, when logging in, using a password, but ssh also allows a client key. The client key is a public key cryptography key pair (consisting of a public and private key). This is a very powerful feature:

The server no longer needs to know a password for you at all. If someone breaks into the server, they can't get your secret password at all.
You can load your private ssh key into an ssh agent, and then you don't need to type either a password or the key's passphrase. If you log into other machines often, this is a time saver.
You can have a key without a passphrase, which allows a cron job or other batch processes to run stuff on other machines in a reasonably secure manner. The server can further be configured to limit what can be executed using the key.

The more powerful features of ssh can be used wrongly, and can have security risks. You should read the documentation to understand the impact of what you're doing.

Installation

Every Linux distribution and BSD system comes with ssh, and usually at least the client is installed by default. You may need to install the server separately. We'll skip the installation instructions: you're hacker enough to figure that out for your particular system, and installation instructions are really boring to write.

Shell builtins, which should you know?

Shell builtins are things which look like commands but are built into the shell rather than being sub-processes which get run. Builtins are typically the control-flow commands such a while and for (which will be covered in another article about shell scripting) but are also commands which affect the state of the shell itself, such as cd or set.

`cd`

The cd command changes the current-working-directory of the shell. It is the builtin command which you use to navigate the filesystem in your shell. It can be used to change to any directory (to which you have access) and can be given a relative or absolute path.

For example: cd /tmp will change to the /tmp directory (where temporary files tend to go), where as cd work will change to the work directory which is inside your current working directory, wherever that is.

In addition, if cd - is entered then the shell will typically change to the previously selected directory, and cd on its own will change to your home directory (typically something like /home/MYUSERNAME).

There's more to cd than even that, but you can read your shell's manual page to learn more.

`pwd`

Interestingly, pwd does not have to be a builtin, although it typically is. The pwd builtin prints the current working directory to its output. pwd is even less complex than cd and if you want to know more about it, then read your shell's manual page, it will detail the rest.

`exit`

The exit builtin terminates the shell which runs it. It can take an argument which is the exit code to return to the calling process. More on that in a future article about shell scripting.

More builtins

There are plenty more builtins, you should look at your shell's manual page for more information about them:

The 'Builtins' section of dash(1) for example.

Useful shell commands for your toolbelt

The more complex commands used from the shell are typically external applications which get run when you invoke them from the shell. We've already encountered the ls command which lists files. We won't go into more detail on that one here, so you should read ls(1) to learn more about it.

`cat`

The cat command 'concatenates' the files listed as arguments. However in simplistic use it can be used to display the contents of a file to your terminal. For example cat /etc/hostname will show you the name of the computer your shell is running on.

You can read more in the cat(1) manual page.

`less` is `more`

When you want to view a larger file, using a pager can help. A pager is so-called because it pages its input to the terminal, waiting for you to indicate that you're ready to read more of the file before it displays it. more is the traditional Unix pager, and in good Unix tradition, when someone wanted to replace it they wrote less because, as we all know, less is more.

less is a very capable application, but in basic use, less /etc/services is the sort of command you'll want to view a larger file such as this list of service name to port number mappings (/etc/services).

If you want to know all the things that less can do, then look at the less(1) manual page.

`cp`

When you need to copy a file (or collection of files) from one place to another then cp is your friend. In its most basic use, you can copy a file from one place to another with cp currentname newname. cp can cope with the newname being a directory in which case the file will be copied into the target directory using the same leafname as is in currentname, for example: cp /etc/passwd /tmp/ will copy the file /etc/passwd into /tmp/passwd.

It's possible to use cp to copy entire directory structures, or multiple input files (via a glob) to a target directory.

To learn more, read cp(1).

`mv`

When you want to move (or rename) a file, then mv is your friend. With a similar syntax to cp, you simply mv currentname newname and the rename will happen. mv can cope with transferring files between disks (e.g. a USB stick and your HDD) or simply renaming files within a disk.

You can learn more in the mv(1) manual page and if you want to do even more impressive renaming efforts then you could take a look at rename(1) and friends.

`rm`

The final command in our basic toolbelt is rm. This command removes (deletes) files from the computer. It's worth noting here that there is no traditional UNDO for this. If you rm a file, it is gone, unlike if you move to trash in a traditional desktop file manager type application.

The commandline syntax is pretty simple: rm somefile will delete somefile. It's possible to remove entire directory trees and you can learn more about recursive removal, verboseness etc, by reading the rm(1) manual page.

Posted Wed Sep 18 19:03:24 2013 Tags: shell

Lars Wirzenius

The Internet Relay Chat, or IRC, is an ancient online, real-time chat system. When I say ancient, I mean that it started in 1988. There are hundreds of public IRC networks for various purposes. Two important general networks for free software developers are [OFTC] and [FreeNode]. Many larger free software projects have their own networks.

IRC has grown to become one of the main ways in which free software developers keep in touch. It is very useful to know how to use IRC, even if you decide that it isn't something you want to often. On the other hand, many strong friendships have been formed via IRC.

Overview

IRC has users, who can send private messages to each other, and can join channels, which where many people can discuss things together. Anything you send to a channel is visible to everyone on the channel.

There's a lot more details to learn, eventually. To get started, you need to get an IRC client, connect to a server, and join a channel. Some popular IRC clients for free operating systems are:

XChat, for GNOME.
Empathy, also for GNOME.
Konversation, for KDE.
irssi, for terminal lovers; also good if you want to always be on IRC.

A good first network for those interested in free software development is [FreeNode] or wherever the support channel for your operating system of choice is located. For example, Debian uses the [OFTC] network. You could try one of these:

server irc.freenode.org, channel #baserock
irc.oftc.net, channel #debian

All IRC clients have an input box of some kind, usually at the bottom of the window or screen. Anything you write there goes to the channel you've joined, or the other party in the private discussion.

You can also type in commands in the input box. These start with a slash (/). Some examples:

/quit exits IRC.
/join #foo joins channel #foo. Anything you write that is not a command will now go to the channel.
/part leaves a channel.
/msg liw_ hi there sends a private message to the user known as liw_ (that's called their nickname on IRC).
/query liw_ opens a window or tab for a discussion with the user. Within this window or tab anything you write will go to the person.

There's tons more commands. Some will be specific to your IRC client, others will be interpreted by the server. The above will get you started, however.

Etiquette

If you join a channel full of people you don't know, you should be careful. You are effectively entering their shared livingroom, and you should take not to make a fool of yourself. A good rule of thumb is to be polite, and listen more than you speak. There's no need to grovel, though.

Avoid sending private messages to people you don't know. It's like calling someone you don't know: you're intruding on their time, and demanding attention.

Language

IRC discussions are often full of jargon and special acronyms. You'll learn these eventually, and looking them up in, for example, the [Jargon file] is a good idea. Sometimes Wikipedia, or a general search engine lookup, will also be quite useful. In other cases, the word or acronym is special to that group of people, and you may need to ask them to explain.

Some examples:

afaik: as far as I know
brb: be right back
iirc: if I recall correctly
lol: laugh out loud
RFTM: read the f... manual