Emulating a z/OS Mainframe with Hercules

Note: I started writing this article back in 2015 and hit a few roadblocks that I’ve been able to finally reconcile in the last few months. There are a lot of similar guides out there (which I will reference in my sources), but I found them to be too ambiguous to be completely helpful. While I’ve learned a lot from writing this and troubleshooting the issues from existing¬†guides, I am still far from a mainframe expert. There may be errors here, or things I could have accomplished in a better, more “proper” way. That said, I ultimately have a usable z/OS system up and running, and I hope I can help you have the same ūüôā

Introduction

I recently became aware of the fact that mainframes are still alive and well in the corporate world. But why? Why not just use supercomputers? Mainframes aim to perform a high number of instructions¬†per second, usually measured in the millions. If you hear someone talking about millions of instructions per second (MIPS), they’re probably measuring mainframe throughput. Supercomuters on the other hand aim to have a high number of floating-point operations per second (FLOPS). The difference is that mainframes usually deal with information processing in a short window while supercomuters usually deal with simulations requiring a lot of floating-point arithmetic. A supercomputer might be more suited to weather calculations on Jupiter, but a mainframe is still a better candidate for processing a lot of transactions like you might find in banking or airline booking systems.

Okay, but why not use some sort of content distribution network or cloud computing? For years, mainframes have been touted as the go-to for mission critical processing, with minimal downtime. While cloud computing is catching up in this regard, it can be argued that mainframes are still unrivaled when considering their efficiency and maintainability. One mainframe may be able to process a chunk of data more efficiently than thousands of linked machines in remote locations. Now, consider maintenance. Would you rather update one machine or thousands? And scalability? Many cloud providers supply controls to ramp up power when needed (such as during the holidays) or dial it back during more sleepy periods. Mainframes offer the same sort of control, and can easily scale up or down as needed without someone (or piece of software) needing to roll out or switch off a few hundred more servers.

Mainframes are an interesting piece of technology that still have a purpose, but they rarely discussed these days with the influx of new technologies in processing. It’s easy to try these services out, even for an amateur, but getting your hands on a mainframe is incredibly difficult in comparison. Even if you happened to be employed at a company still utilizing one, you would need training and shadowing sessions before even having the chance to touch a keyboard on a production machine.

Of course, there are ways to explore these systems without needing a physical unit, and that is what I’m going to get into momentarily. It is now possible to get your own taste of Big Iron right from your personal computer.

Requirements

Before we get into installing Hercules, an IBM mainframe emulator, you are going to need to find an image of z/OS. z/OS is the operating system of choice for modern IBM mainframes, but it is a little hard to get your hands on unless you actually have a full-scale system set up somewhere already. There are images of z/OS floating around the Internet that can be found, specifically version 1.10. I will not be sharing where these files can be found, and if you do find them, make sure you adhere to the software license while running z/OS.

Now, we also need a host system to support the Hercules emulator. While Hercules will run in Linux, Windows, and OSX, this guide will use a machine running Linux, specifically Debina 9 (Stretch). I will assume that you already have a system running Debian (or similar) and a non-root, sudo user with access to the z/OS files.

After all of this is set up, we can begin installation!

Configuring Hercules and c3270

First, we need to install some basic utilities and applications. But, one of them (c3270) is not available right away as it is classified as “non-free” software under Debian. You can still install packages like this, you just need to configure your system to do so. We need to edit the sources.list file to allow non-free packages.

Simply add non-free to the end of the stretch and stretch-updates sources by editing /etc/apt/sources.list with your favorite text editor:

$ sudo nano /etc/apt/sources.list

After editing, it should look like this:

$ cat /etc/apt/sources.list

deb http://ftp.us.debian.org/debian/ stretch main non-free
deb-src http://ftp.us.debian.org/debian/ stretch main non-free

deb http://security.debian.org/debian-security stretch/updates main
deb-src http://security.debian.org/debian-security stretch/updates main

# stretch-updates, previously known as 'volatile'
deb http://ftp.us.debian.org/debian/ stretch-updates main non-free
deb-src http://ftp.us.debian.org/debian/ stretch-updates main non-free

Now we are ready to install the packages we need. All of them can be installed by running the following command:

$ sudo apt-get install -y c3270 hercules

As this starts executing, go and put on a pot of coffee. As soon as you turn the machine on and walk back to your computer, this command will probably be through.

The above has installed hercules, our IBM system emulator as well as c3270, a IBM 3270-compatible terminal emulator that we will use to interface with our system.

Now, I’m going to assume you have the z/OS files somewhere on your Linux machine, possibly in a directory path like IBM\ ZOS\ 1.10/Z110SA/images/Z110\ -\ Copy. I will assume that the root IBM folder is in your home directory. We will reorder things by creating a directory MAINFRAME within the home directory to house the z/OS installation:

$ cd ~
$ mv IBM\ ZOS\ 1.10/Z110SA/images/Z110\ -\ Copy ~/MAINFRAME
$ cd ~/MAINFRAME
$ mkdir PRTR

We will now have the following heirarchy:

$ ls ~/MAINFRAME
CONF DASD PRTR

At this point, we need to edit the config file that Hercules reads to boot our mainframe. You can open up the config file in your favorite text editor and follow along with the lines we will modify:

$ nano ~/MAINFRAME/CONF/ADCD_LINUX.CONF

First, we need to edit lines 38/39/40 of the config to map to your PRTR, CONF, and DASD directories in your ~/MAINFRAME directory. We will be using full directory paths, so use your username in place of mine, famicoman.

#********************************************************************
# SYMBOLS DEFINITION *
#********************************************************************

DEFSYM DASD "/home/famicoman/MAINFRAME/DASD"
DEFSYM PROD "/home/famicoman/MAINFRAME/PROD"
DEFSYM PRTR "/home/famicoman/MAINFRAME/PRTR"

Now, we edit networking information on line 115. We will need two unused IP addresses on our local network. We can get our machine’s current IP address using the ip command.

$ ip address show eno1
2: eno1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000
link/ether fc:3f:db:09:60:59 brd ff:ff:ff:ff:ff:ff
inet 192.168.1.248/24 brd 192.168.1.255 scope global dynamic eno1
valid_lft 81093sec preferred_lft 81093sec
inet6 fe80::fe3f:dbff:fe09:6059/64 scope link
valid_lft forever preferred_lft forever

Our Debian machine is located at 192.168.1.248. We can pick two additional addresses in the 192.168.1.1 Р192.168.1.254 range. 192.168.1.20 and 192.168.1.21 are currently unused so these will be chosen. 192.168.1.20 will be something of a virtual gateway for the mainframe (think of this sort of like an address for Hercules itself, which we will use as our entry point) while 192.168.1.21 will be an address for the z/OS machine. Keep in mind that 192.168.1.20 will be exposed to your network independently of your host machine, creating a logically separate machine. This means you can access it with its own address, and create separate firewall rules, port forwarding, etc. as though it was physical machine on your LAN.

We will replace the content at line 115 in the config with the following to create a virtual adapter to handle networking with our chosen addresses:

#********************************************************************
# CTCI COMMUNICATION DEVICES *
#********************************************************************
0E20.2 3088 CTCI /dev/net/tun 1500 192.168.1.20 192.168.1.21 255.255.255.255

Lastly, we edit line 31. This line changes the default port for Hercules console connections (made by c3270) from 23 to something of your choosing. I will be using port 2323 as I may be using port 23 otherwise, and it is not a privileged port.

CNSLPORT 2323

Now we can launch Hercules! (Do you smell your coffee percolating yet?)

I prefer to use screen sessions to keep thing organized (If you don’t have screen, install it with sudo apt-get install screen or just use tmux). This is also handy with using a virtual or remote host machine as you can keep the sessions going when not connected to the host. The below will place you in a new screen session where we will launch Hercules:

$ screen -S hercules

And now for the launch, specifying the config we edited earlier:

$ sudo hercules -f ~/MAINFRAME/CONF/ADCD_LINUX.CONF

Hercules will begin to load (and give you a lot of logs). Then you will be presented with the Hercules console.

The Hercules console after launching. Note our tun0 device opening and our custom console port specified.

Now, we want to create a 3270 terminal session with Hercules. So, hold <CTRL> + A + D to detach your screen session, returning you to your original console window on the Debian host. Next, create a new screen session for our 3270 connection:

$ screen -S c3270

Now in our new screen session, we will launch c3270 to connect into Hercules, emulating a 3270 connection to actual hardware:

c3270 localhost 2323

You should be presented with a Hercules splash screen:

The Hercules splash screen.

Detach from your c3270 screen session and reattach to the hercules session. It might be a good idea to open a new terminal window on the host machine to keep multiple screen sessions open at once. I suggest two terminal windows, one with hercules and one with c3270. To reattach your hercules screen session, use the below command after detaching:

$ screen -r hercules

Now that you are presented with the Hercules console again, you should see your connection from the 3270 session in the logs.

HHCTE009I Client 127.0.0.1 connected to 3270 device 0:0700

Booting z/OS

Now we can boot z/OS for the first time! In the Hercules console, type the following and hit <RETURN>:

ipl a80

z/OS will now boot. Your coffee should be done by now, so go grab a cup. I’ll wait.

Depending on the specs of the host machine, this could take a long, long time. The first boot took around 90 minutes for me, and could take even longer. At this point, you will get a lot of logging info in both the c3270 session and the hercules session. A lot of this looks like it could be reporting that something has gone horribly wrong, but don’t worry, it is likely okay. This is probably a good time to go for a walk outside with your coffee. Maybe take a good book and settle under a tree for a bit.

A Potential Boot Issue

I did run into the following message on my c3270 session at some point while attempting boot:

IXC208I THE RESPONSE TO MESSAGE IXC420D IS INCORRECT: IS NOT A VALID
ACTION
IXC420D REPLY I TO INITIALIZE SYSPLEX ADCDPL, OR R TO REINITIALIZE
XCF.
REPLYING I WILL IMPACT OTHER ACTIVE SYSTEMS.

If this happens to you, you can safely type the following in the c3270 session and hit <RETURN>:

R 00,I

This will allow z/OS to continue booting.

This message in the 3270 console halted boot-up. Entering the provided command can resume system startup.

If you are unsure whether or not z/OS is fully booted (It can be hard to tell), the easiest thing to do is open another c3270 connection to localhost (maybe create a new screen¬†session via screen -S terminal). If you get the Hercules splash screen again you can safely close the session (<CTRL> + ], then type “exit”), wait a little longer, and try connecting again. Eventually, your second terminal session should connect and get to the log-on screen for your z/OS installation.

Welcome to the DUZA system!

To log in, we enter”TSO” at the prompt. When prompted for a username, enter “IBMUSER”.

Login starts by asking for a USERID.

Then, enter “SYS1” as the password.

The password gets blanked out as you type it.

From here, press <RETURN>, then the ISPF menu will launch.

You will get some brief messages after logging in. Press the <RETURN> key to go to the ISPF menu.

 

The ISPF menu serves as a gateway to a lot of system functionality.

Now in the ISPF menu, type “3.4” to load the Data Set List Utility.

Replace “IBMUSER” in the “Dsname Level” field with “DUZA” and press <RETURN>.

We will use the Data Set List Utility to locate our network settings.

Scroll down using the <F8> key in the Data Sets list and locate the one called DUZA.TCPPARAMS. With your cursor, click on the ‘D’ in “DUZA.TCPARAMS” and use the left-arrow key to navigate three spaces to the left. Type the letter ‘E’ and hit <RETURN> to see items in this data set.

We need to edit the TCPPARAMS for the DUZA system.

On the next screen, use your cursor to click on the first position on the line to the left of the word “PROFILE”. Type the letter ‘E’ and hit <RETURN> to edit this item.

Finally, we can edit the Profile.

Use <F8> to page down to line 90:

000090 DEVICE LCS1 LCS E20
000091 LINK ETH1 ETHERNET 0 LCS1
000092
000093 HOME
000094 10.0.1.20 ETH1
000095
000096 GATEWAY
000097 10.0.1.100 = ETH1 1500 HOST
000098
000099 DEFAULTNET 10.0.1.100 ETH1 1500 0
...
000109 START LCS1

Modify the lines so they look like the following with out IP addresses outlined earlier (and don’t forget line 109!):

000090 DEVICE CTCA1 CTC e20
000091 LINK CTC1 CTC 1 CTCA1
000092
000093 HOME
000094 192.168.0.210 CTC1
000095
000096 GATEWAY
000097 192.168.0.1 = CTC1 1492 HOST
000098
000099 DEFAULTNET 192.168.0.5 CTC1 1492
...
000109 START CTCA1

To save the updated config, place your cursor to the first underline character to the right of “Command ===>” and type “SAVE” followed by the <RETURN> key. Next, type “END” at the same location, again pressing the <RETURN> key.

Here is what the updated settings look like via the 3270 terminal:

Our updated networking is ready to save. Note the IP addresses we specified earlier when configuring Hercules.

Next, we need to recycle the TCPIP service on the system. Go back to your first c3270 console session (detaching your terminal¬†session) and type¬†“STOP TCPIP” followed by the <RETURN> key in the console.

STOP TCPIP.

Wait a minute or two and then type “START TCPIP” followed by the <RETURN> key. After both commands, you should see a lot of console output regarding the TCPIP service. After starting the service back up, wait a few minutes before proceeding to make sure everything has come back up.

After running START TCPIP.

After restarting the TCP service, we need to detach the session and do a few more things on our host machine.

Back on the Debian host machine we need to enable IPv4 forwarding and proxy arp with the following two commands to get networking sorted out:

$ sudo sh -c "echo '1' > /proc/sys/net/ipv4/conf/all/proxy_arp"
$ sudo sh -c "echo '1' > /proc/sys/net/ipv4/conf/all/forwarding"

Testing Networking

We can now test whether we can remote into our z/OS machine, and if we can get out from the inside. From the console on the host Debian machine, telnet to our mainframe using port 1023:

$ telnet 192.168.1.20 1023

Login with the credentials we used earlier (IBMUSER/SYS1) and try out a traceroute command:

Trying 192.168.1.20...
Connected to 192.168.1.20.
Escape character is '^]'.
EZYTE27I login: IBMUSER
EZYTE28I IBMUSER Password:
IBM
Licensed Material - Property of IBM
5694-A01 Copyright IBM Corp. 1993, 2008
(C) Copyright Mortice Kern Systems, Inc., 1985, 1996.
(C) Copyright Software Development Group, University of Waterloo, 1989.

All Rights Reserved.

U.S. Government Users Restricted Rights -
Use,duplication or disclosure restricted by
GSA ADP Schedule Contract with IBM Corp.

IBM is a registered trademark of the IBM Corp.

IBMUSER:/u/ibmuser: >traceroute 8.8.8.8
CS V1R10: Traceroute to 8.8.8.8 (8.8.8.8)
Enter ESC character plus C or c to interrupt
1 192.168.1.21 (192.168.1.21)  1 ms  1 ms  1 ms
2 192.168.1.1 (192.168.1.1)  70 ms  4 ms  3 ms
3 71.185.57.1 (71.185.57.1)  5 ms  6 ms  4 ms
4 100.41.14.204 (100.41.14.204)  10 ms 100.41.14.206 (100.41.14.206)  8 ms 100.41.14.204 (100.41.14.204)  10 ms
5 * * *
6 * * *
7 140.222.0.187 (140.222.0.187)  10 ms 140.222.2.201 (140.222.2.201)  9 ms 140.222.0.187 (140.222.0.187)  6 ms
8 204.148.79.46 (204.148.79.46)  16 ms  11 ms  11 ms
9 108.170.246.33 (108.170.246.33)  12 ms 108.170.246.1 (108.170.246.1)  12 ms 108.170.240.97 (108.170.240.97)  10 ms
10 108.170.226.95 (108.170.226.95)  10 ms 209.85.254.75 (209.85.254.75)  15 ms 216.239.41.203 (216.239.41.203)  12 ms
11 8.8.8.8 (8.8.8.8)  11 ms  19 ms  10 ms

You can additionally try out some more Unix commands:

IBMUSER:/u/ibmuser: >uptime
07:55PM  up 6 day(s), 03:54,  1 users,  load average: 0.00, 0.00, 0.00
IBMUSER:/u/ibmuser: >uname -a
OS/390 DUZA 20.00 03 7060
IBMUSER:/u/ibmuser: >whoami
OMVSKERN
IBMUSER:/u/ibmuser: >ls
CEEDUMP.20050812.162501.65568  ptest.c                        setup1
SimpleCopy.class               ptest.o                        setup2
SimpleCopy.java                ptestc                         setup3
hfsin                          ptestc.trc.16842781            zfs
hfsout                         setup

Back in your second 3270 connection (which like me you may have named terminal), you can keep entering”EXIT” in the “Command ===>” field until you return back to the ISPF menu we saw earlier.

There are many options from the ISPF menu. Take some time to explore them when you get a chance!

From here, you can enter “6” in the “Option ===>” field to get to the Command menu. From here, you can try out other various commands like ping¬†or netstat by¬†entering them into the “===>” field.

Here is the output of netstat. Notice how previously used commands are cached for you.

Shutting it Down

You always want to make sure to shut down your mainframe in the proper way. Otherwise, you may end up with corrupted data or an unbootable system!

From your first c3270 session, enter in¬†“S SHUTSYS”.

S SHUTSYS

Then after a little while enter in “Z EOD”.

Z EOD

Starting the shutdown process.

After a few minutes the machine will halt. Then, switch over to your Hercules console and enter in “exit” to close out Hercules.

exit

Rebooting the mainframe follows the same start-up process from initial boot, so you can easily come back to things.

Conclusion

That’s it, you now have a functioning mainframe! Albeit, it will be much slower than a real mainframe on real hardware (emulation on my machine usually only clocks between 5-12 MIPS).

Toggle back and forth between the console and graphical view in Hercules with the <ESC> key.

Feel free to explore the system, and start learning how to use z/OS and customize your installation!

Sources

 

Configuring a Tor Hidden Service

Tor hidden services allow various types of services (web server, telnet server, chat server, etc) to be operated within the Tor network. This allows both users and service operators to conceal their identities and locations. Just about anything that can be run on the clearnet can be run within the Tor darknet.

Setting up a hidden service on Tor is a simple process and depending on the level of detail, an operator can keep their service completely anonymous. Depending on your use-case, you may or may not choose to anonymize your service at all. For anonymous operation, it is recommended to bind services being offered to localhost and make sure that they do not leak information such as an IP address or hostname in any situation (such as with error messages).

For this guide, we assume a Debian Stretch (or similar) Linux system with a non-root, sudo user. It is also assumed that the target machine has been set up with some standard security practices such as disallowing root logins over SSH, and basic firewall rules. This Tor hidden service will be masked on the darknet, but if the hosting server is deanonymized, a malicious party could uncover the machine’s actual clearnet IP address and attempt to penetrate it or otherwise disrupt service. Depending on the software running the services you are hiding, you may wish to install into a virtual machine to limit damage to the system by code vulnerabilities.

Installing Tor

Before configuring a relay, the Tor package must be set up on the system. While Debian does have a Tor package in the standard repositories, we will want to add the official Tor repositories and install from there to get the latest software and be able to verify its authenticity.

First, we will edit the sources list so that Debian will know about the official Tor repositories.

$ sudo nano /etc/apt/sources.list

At the bottom of the file, paste the following two lines and save/exit.

deb http://deb.torproject.org/torproject.org stretch main
deb-src http://deb.torproject.org/torproject.org stretch main

Now back in the console, we will add the Tor Project’s GPG key used to sign the Tor packages. This will allow verification that the software we are installing has not been tampered with.

$ gpg --keyserver keys.gnupg.net --recv A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89
$ gpg --export A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89 | sudo apt-key add -

Lastly, run an update and install Tor from the repositories we just added.

$ apt-get update
$ apt-get install tor deb.torproject.org-keyring

 

Configuring the Hidden Service

We will be editing the torrc file, so let’s bring it up in our text editor:

$ sudo nano /etc/tor/torrc

Going line by line in this file is tedious, so to minimize confusion, we will ultimately rewrite the whole file. We will implement logging into a file located at /var/log/tor/notices.log and assume the local machine has a web server running on port 80. Paste the following over the existing contents in your torrc file:

Log notice file /var/log/tor/notices.log

############### This section is just for location-hidden services ###

## Once you have configured a hidden service, you can look at the
## contents of the file ".../hidden_service/hostname" for the address
## to tell people.
##
## HiddenServicePort x y:z says to redirect requests on port x to the
## address y:z.

HiddenServiceDir /var/lib/tor/hs_name_of_my_service/
HiddenServicePort 80 127.0.0.1:80

#HiddenServiceDir /var/lib/tor/other_hidden_service/
#HiddenServicePort 80 127.0.0.1:80
#HiddenServicePort 22 127.0.0.1:22

After saving the file, make and permission a log file, then we are ready to restart Tor:

$ sudo touch /var/log/tor/notices.log
$ chown debian-tor:debian-tor /var/log/tor/notices.log
$ sudo service tor restart

If the restart was successful, the Tor hidden service is active. If not, be sure to check the log file for hints as to the failure:

$ sudo nano /var/log/tor/notices.log

Now that the hidden service is working, Tor has created the hidden service directory we defined in the torrc, /var/lib/tor/hs_name_of_my_service/. There are two files of importance within this directory.

There is a hostname file at /var/lib/tor/hs_name_of_my_service/hostname that contains the hidden service’s public key. This public key acts as a .onion address which users on the Tor network can use to access your service. Make a note of this address after reading it from the file with cat:

$ sudo cat /var/lib/tor/hs_name_of_my_service/hostname
nb2tidpl4j4jnoxr.onion

There is also a private_key file that contains the hidden service’s private key. This private key pairs with the service’s public key. It should not be known or read by anyone or anything except Tor, otherwise someone else will be able to impersonate the hidden service. If you need to move your Tor hidden service for any reason, make sure to backup the hostname and private_key files before restoring them on a new machine.

After restarting the hidden service, it may not be available right away. It can take a few minutes before the .onion address resolves on a client machine.

 

Example – Configure A Web Server with Nginx

Let’s use this hidden service to host a website with Nginx.

First, we will install Nginx and create a directory for our HTML files

$ sudo apt-get install nginx
$ sudo mkdir -p /var/www/hidden_service/

Now, we will create an HTML file to serve, so we need to bring one up in our editor:

$ sudo nano /var/www/hidden_service/index.html

Paste the following basic HTML and save it:

<html><head><title>Hidden Service</title></head><body><h1>It works!</h1></body></html>

Next, we will set the owner of the files we created to www-data for the web server and change the permissions on the /var/www directory.

$ sudo chown -R www-data:www-data /var/www/hidden_service/
$ sudo chmod -R 755 /var/www

We want to make some configuration changes for anonymity. First, let’s edit the default server block:

$ sudo nano /etc/nginx/sites-available/default

Find the block that starts with server { and you should see a line below that reads #listen 80;. Replace this line with to explicitly listen on localhost:

listen localhost:80 default_server;

Now find the line in the block for server_name  set the server name explicitly:

server_name _;

Next we need to edit the Nginx configuration file:

$ sudo nano /etc/nginx/nginx.conf

Find the block that starts with http { and set the following options:

server_name_in_redirect off;
server_tokens off;
port_in_redirect off;

The first option will make sure the server name isn’t used in any redirects. The second option removes server information in error pages and headers. The third option will make sure the port number Nginx listens on will not be included when generating a redirect.

Now we need to create a server block so Nginx knows which directory to serve content from when our hidden service is accessed. Using our text editor, we will create a new server block file:

$ sudo nano /etc/nginx/sites-available/hidden_service

In the empty file, paste the following configuration block. Make sure that the server_name field contains your onion address which you read from the hostname file earlier and not my address, nb2ticpl4j4hnoxq.onion.

server {
listen   127.0.0.1:80;
server_name nb2tidpl4j4jnoxr.onion;

error_log   /var/log/nginx/hidden_service.error.log;
access_log  off;

location / {
        root /var/www/hidden_service/;
        index index.html;
    }
}

After saving the file, we need to symlink it to the sites-enabled directory and then restart Nginx:

$ sudo ln -s /etc/nginx/sites-available/hidden_service /etc/nginx/sites-enabled/hidden_service
$ sudo service nginx restart

To test the hidden service, download and install the Tor Browser on any machine and load up your .onion address.

 

Example – Configure A Web Server with Apache

Let’s use this hidden service to host a website with Apache. Note: Many criticize Apache for leaking server information by default. Apache takes more effort to secure.

First, we will install Apache and create a directory for our HTML files

$ sudo apt-get install apache2
$ sudo mkdir -p /var/www/hidden_service/

Now, we will create an HTML file to serve, so we need to bring one up in our editor:

$ sudo nano /var/www/hidden_service/index.html

Paste the following basic HTML and save it:

<html><head><title>Hidden Service</title></head><body><h1>It works!</h1></body></html>

Next, we will set the owner of the files we created to www-data for the web server and change the permissions on the /var/www directory.

$ sudo chown -R www-data:www-data /var/www/hidden_service/
$ sudo chmod -R 755 /var/www

Now, we need to make a few changes to the Apache configuration. Let’s start by setting Apache up to only listen to port 80 on 127.0.1.1:

$ sudo nano /etc/apache2/ports.conf

Change the line Listen 80 to Listen 127.0.0.1:80 and save the file.

Now we will access the security configuration file:

$ sudo nano /etc/apache2/conf-enabled/security.conf

Change the line for ServerSignature to ServerSignature Off and the line for ServerTokens to ServerTokens Prod to restrict information the httpd reports about the server.

Then, we will make an edit to the main Apache configuration file to override the server name Apache uses:

$ sudo nano /etc/apache2/apache2.conf

At the very bottom of the file, paste the following. Make sure that the ServerName field contains your onion address which you read from the hostname file earlier and not my address, nb2tidpl4j4jnoxr.onion.

ServerName nb2tidpl4j4jnoxr.onion

Next, we will disable Apache’s mod_status module to turn off status information:

$ sudo a2dismod status

Now we need to create a virtual host so Nginx knows which directory to serve content from when our hidden service is accessed. Using our text editor, we will create a new server block file:

$ sudo nano /etc/apache2/sites-available/hidden_service

In the empty file, paste the following configuration block. Make sure that the server_name field contains your onion address which you read from the hostname file earlier and not my address, nb2tidpl4j4jnoxr.onion.

<VirtualHost *:80>

 ServerName  nb2ticpl4j4hnoxq.onion

 DirectoryIndex index.html
 DocumentRoot /var/www/hidden_service/

  CustomLog /dev/null common

</VirtualHost>

After saving the file, we need to symlink it to the sites-enabled directory and then restart Nginx:

$ sudo ln -s /etc/apache2/sites-available/hidden_service /etc/apache2/sites-enabled/hidden_service
$ sudo service apache2 restart

To test the hidden service, download and install the Tor Browser on any machine and load up your .onion address.

 

Conclusion

Your hidden service should be up and running, ready to server Tor users. Now that your relay is functioning, it may be a good idea to back up your hostname and private_key files mentioned earlier in the /var/lib/tor/hs_name_of_my_service/ directory.

I would strongly recommend taking a look at riseup.net’s Tor Hidden Services Best Practices guide to learn more about proper setup of your hidden service.

Additionally, subscribe to the tor-onions mailing list for operator news and support!

Sources

 

Configuring and Monitoring a Tor Middle Relay

The Tor network relies upon individuals and organizations to donate relays for user traffic. The more relays within network, the stronger and faster the network is. Below, we will create a middle relay which receives traffic and sends it off to another relay. Middle relays will never serve as exit points for traffic back out to the clear Internet (a job for an exit relay). Because of this, many see running a middle relay as a safer way of contributing to the Tor network as opposed to running an exit relay which could find an operator at fault if illegal activity or content exits his node.

For this guide, we assume a Debian Stretch (or similar) Linux system with a non-root, sudo user. It is also assumed that the target machine has been set up with some standard security practices such as disallowing root logins over SSH, and basic firewall rules. This Tor relay will be public, and should be secured like any public-facing server.

 

Installing Tor

Before configuring a relay, the Tor package must be set up on the system. While Debian does have a Tor package in the standard repositories, we will want to add the official Tor repositories and install from there to get the latest software and be able to verify its authenticity.

First, we will edit the sources list so that Debian will know about the official Tor repositories.

$ sudo nano /etc/apt/sources.list

At the bottom of the file, paste the following two lines and save/exit.

deb http://deb.torproject.org/torproject.org stretch main
deb-src http://deb.torproject.org/torproject.org stretch main

Now back in the console, we will add the Tor Project’s GPG key used to sign the Tor packages. This will allow verification that the software we are installing has not been tampered with.

$ gpg --keyserver keys.gnupg.net --recv A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89
$ gpg --export A3C4F0F979CAA22CDBA8F512EE8CBC9E886DDD89 | sudo apt-key add -

Lastly, run an update and install Tor from the repositories we just added.

$ apt-get update
$ apt-get install tor deb.torproject.org-keyring

 

Keeping Time

It is important that a Tor relay keeps accurate time, so we will change the timezone and set up the ntp client.

First, list timezones to and find which one corresponds to the location of the machine:

$ timedatectl list-timezones

Next, we set the timezone to the one for the machine’s location. Amsterdam is used below as an example.

$ sudo timedatectl set-timezone Europe/Amsterdam

Finally, install ntp:

$sudo apt-get install ntp

You can check your changes using the timedatectl command with no options:

$ timedatectl
      Local time: Sat 2017-12-30 21:49:25 CET
  Universal time: Sat 2017-12-30 20:49:25 UTC
        RTC time: Sat 2017-12-30 20:49:25
       Time zone: Europe/Amsterdam (CET, +0100)
     NTP enabled: yes
NTP synchronized: yes
 RTC in local TZ: no
      DST active: no
 Last DST change: DST ended at
                  Sun 2017-10-29 02:59:59 CEST
                  Sun 2017-10-29 02:00:00 CET
 Next DST change: DST begins (the clock jumps one hour forward) at
                  Sun 2018-03-25 01:59:59 CET
                  Sun 2018-03-25 03:00:00 CEST

 

Configuring the Relay

By default, all new relays are set up to be exit nodes. Since we want to create a middle relay, there is some configuration that needs to be done.

We will be editing the torrc file, so let’s bring it up in our text editor:

$ sudo nano /etc/tor/torrc

Going line by line in this file is tedious, and to minimize confusion, I will outline some configuration outlines and paste a sample torrc file below that you can use with minimal changes.

  • We don’t need a SOCKS proxy, so uncomment the line SOCKSPolicy reject *
  • We want to keep a separate log file, so uncomment the line Log notice file /var/log/tor/notices.log
  • We will be running as a daemon, so uncomment the line RunAsDaemon 1
  • We will be running monitoring via ARM, so uncomment the line ControlPort 9051
  • Relays need an ORPort for incoming connections, so uncomment the line ORPort 9001
  • It is recommended that a relay has an FQDN or at least a subdomain of one. If not, the machine’s IP address can be used. We will unncomment the line Address noname.example.com and use our address in place of noname.example.com
  • The relay should also have a nickname, so uncomment the line Nickname ididnteditheconfig and use our own nickname in place of ididnteditheconfig
  • Contact information should also be provided, so uncomment the line #ContactInfo Random Person and use our own info in place of Random Person
  • We will be running a directory port, so uncomment the line DirPort 9030
  • The most important option, we don’t want to allow any exits, so uncomment the line ExitPolicy reject *:*
  • Optionally, we may want to limit the bandwidth that Tor uses. To do so, uncomment the lines RelayBandwidthRate 100 KBytes and RelayBandwidthBurst 200 KBytes. These values are defined for one way transport, so note that the actual bandwidth rate above could be 200KB/s total (100KB/s for each input and output). Burst defines a maximum rate, so a burst of 200 KBytes means bandwidth could reach 400KB/s total (combined input and output). Many will likely want their relay to be considered Fast by the network, meaning that the relay’s bandwidth is in the top 7/8ths of all relays. At the time of writing, a rate of¬†500 KBytes/s seems to be on the low end of achieving this according to a Tor team member.
  • Optionally, we may want to limit the total traffic Tor uses over a period. To do so, uncomment the lines AccountingMax 40 GBytes and AccountingStart month 3 15:00. The AccountingMax value is defined for one way transport, so note that setting 40 GBytes could use 80 GBytes total (40 GBytes for each input and output). If the machine is on a provider that limits monthly bandwidth, it is a good idea to adjust this value to align with the provider’s data cap and adjust the AccountingStart values to reset to reset when the data cap does. NOTE: If you do set accounting, the relay will not advertise a directory port and you will not get directory connections. Relays with directories are expected to have a lot of bandwidth and limiting it will result in other nodes not making directory connections.

Now, here is a full sample torrc file for the tor middle relay:

## Configuration file for a typical Tor user

## Tor opens a SOCKS proxy on port 9050 by default -- even if you don't
## configure one below. Set "SOCKSPort 0" if you plan to run Tor only
## as a relay, and not make any local application connections yourself.
#SOCKSPort 9050 # Default: Bind to localhost:9050 for local connections.
#SOCKSPort 192.168.0.1:9100 # Bind to this address:port too.

## Entry policies to allow/deny SOCKS requests based on IP address.
## First entry that matches wins. If no SOCKSPolicy is set, we accept
## all (and only) requests that reach a SOCKSPort. Untrusted users who
## can access your SOCKSPort may be able to learn about the connections
## you make.
#SOCKSPolicy accept 192.168.0.0/16
#SOCKSPolicy accept6 FC00::/7
SOCKSPolicy reject *

## Logs go to stdout at level "notice" unless redirected by something
## else, like one of the below lines. You can have as many Log lines as
## you want.
##
## We advise using "notice" in most cases, since anything more verbose
## may provide sensitive information to an attacker who obtains the logs.
##
## Send all messages of level 'notice' or higher to /var/log/tor/notices.log
Log notice file /var/log/tor/notices.log
## Send every possible message to /var/log/tor/debug.log
#Log debug file /var/log/tor/debug.log
## Use the system log instead of Tor's logfiles
#Log notice syslog
## To send all messages to stderr:
#Log debug stderr

## Uncomment this to start the process in the background... or use
## --runasdaemon 1 on the command line. This is ignored on Windows;
## see the FAQ entry if you want Tor to run as an NT service.
RunAsDaemon 1

## The directory for keeping all the keys/etc. By default, we store
## things in $HOME/.tor on Unix, and in Application Data\tor on Windows.
#DataDirectory /var/lib/tor

## The port on which Tor will listen for local connections from Tor
## controller applications, as documented in control-spec.txt.
ControlPort 9051
## If you enable the controlport, be sure to enable one of these
## authentication methods, to prevent attackers from accessing it.
#HashedControlPassword 16:872860B76453A77D60CA2BB8C1A7042072093276A3D701AD684053EC4C
#CookieAuthentication 1

############### This section is just for location-hidden services ###

## Once you have configured a hidden service, you can look at the
## contents of the file ".../hidden_service/hostname" for the address
## to tell people.
##
## HiddenServicePort x y:z says to redirect requests on port x to the
## address y:z.

#HiddenServiceDir /var/lib/tor/hidden_service/
#HiddenServicePort 80 127.0.0.1:80

#HiddenServiceDir /var/lib/tor/other_hidden_service/
#HiddenServicePort 80 127.0.0.1:80
#HiddenServicePort 22 127.0.0.1:22

################ This section is just for relays #####################
#
## See https://www.torproject.org/docs/tor-doc-relay for details.

## Required: what port to advertise for incoming Tor connections.
ORPort 9001
## If you want to listen on a port other than the one advertised in
## ORPort (e.g. to advertise 443 but bind to 9090), you can do it as
## follows.  You'll need to do ipchains or other port forwarding
## yourself to make this work.
#ORPort 443 NoListen
#ORPort 127.0.0.1:9090 NoAdvertise

## The IP address or full DNS name for incoming connections to your
## relay. Leave commented out and Tor will guess.
Address tor.peer3.famicoman.com

## If you have multiple network interfaces, you can specify one for
## outgoing traffic to use.
# OutboundBindAddress 10.0.0.5

## A handle for your relay, so people don't have to refer to it by key.
Nickname peer3famicoman

## Define these to limit how much relayed traffic you will allow. Your
## own traffic is still unthrottled. Note that RelayBandwidthRate must
## be at least 20 kilobytes per second.
## Note that units for these config options are bytes (per second), not
## bits (per second), and that prefixes are binary prefixes, i.e. 2^10,
## 2^20, etc.
RelayBandwidthRate 2048 KBytes  # Throttle traffic to 2048KB/s (16384Kbps)
RelayBandwidthBurst 3072 KBytes # But allow bursts up to 3072KB/s (24576Kbps)

## Use these to restrict the maximum traffic per day, week, or month.
## Note that this threshold applies separately to sent and received bytes,
## not to their sum: setting "40 GB" may allow up to 80 GB total before
## hibernating.
##
## Set a maximum of 40 gigabytes each way per period.
#AccountingMax 400 GBytes
## Each period starts daily at midnight (AccountingMax is per day)
#AccountingStart day 00:00
## Each period starts on the 3rd of the month at 15:00 (AccountingMax
## is per month)
AccountingStart month 24 15:00

## Administrative contact information for this relay or bridge. This line
## can be used to contact you if your relay or bridge is misconfigured or
## something else goes wrong. Note that we archive and publish all
## descriptors containing these lines and that Google indexes them, so
## spammers might also collect them. You may want to obscure the fact that
## it's an email address and/or generate a new address for this purpose.
#ContactInfo Random Person 
## You might also include your PGP or GPG fingerprint if you have one:
#ContactInfo 0xFFFFFFFF Random Person 
ContactInfo famicoman[at]gmail[dot]com - 1DVLNHpcoAso6rvisCnVQbCFN8dRir1GVQ

## Uncomment this to mirror directory information for others. Please do
## if you have enough bandwidth.
DirPort 9030 # what port to advertise for directory connections
## If you want to listen on a port other than the one advertised in
## DirPort (e.g. to advertise 80 but bind to 9091), you can do it as
## follows.  below too. You'll need to do ipchains or other port
## forwarding yourself to make this work.
#DirPort 80 NoListen
#DirPort 127.0.0.1:9091 NoAdvertise
## Uncomment to return an arbitrary blob of html on your DirPort. Now you
## can explain what Tor is if anybody wonders why your IP address is
## contacting them. See contrib/tor-exit-notice.html in Tor's source
## distribution for a sample.
#DirPortFrontPage /etc/tor/tor-exit-notice.html

## Uncomment this if you run more than one Tor relay, and add the identity
## key fingerprint of each Tor relay you control, even if they're on
## different networks. You declare it here so Tor clients can avoid
## using more than one of your relays in a single circuit. See
## https://www.torproject.org/docs/faq#MultipleRelays
## However, you should never include a bridge's fingerprint here, as it would
## break its concealability and potentially reveal its IP/TCP address.
#MyFamily $keyid,$keyid,...

## A comma-separated list of exit policies. They're considered first
## to last, and the first match wins.
##
## If you want to allow the same ports on IPv4 and IPv6, write your rules
## using accept/reject *. If you want to allow different ports on IPv4 and
## IPv6, write your IPv6 rules using accept6/reject6 *6, and your IPv4 rules
## using accept/reject *4.
##
## If you want to _replace_ the default exit policy, end this with either a
## reject *:* or an accept *:*. Otherwise, you're _augmenting_ (prepending to)
## the default exit policy. Leave commented to just use the default, which is
## described in the man page or at
## https://www.torproject.org/documentation.html
##
## Look at https://www.torproject.org/faq-abuse.html#TypicalAbuses
## for issues you might encounter if you use the default exit policy.
##
## If certain IPs and ports are blocked externally, e.g. by your firewall,
## you should update your exit policy to reflect this -- otherwise Tor
## users will be told that those destinations are down.
##
## For security, by default Tor rejects connections to private (local)
## networks, including to the configured primary public IPv4 and IPv6 addresses,
## and any public IPv4 and IPv6 addresses on any interface on the relay.
## See the man page entry for ExitPolicyRejectPrivate if you want to allow
## "exit enclaving".
##
#ExitPolicy accept *:6660-6667,reject *:* # allow irc ports on IPv4 and IPv6 but no more
#ExitPolicy accept *:119 # accept nntp ports on IPv4 and IPv6 as well as default exit policy
#ExitPolicy accept *4:119 # accept nntp ports on IPv4 only as well as default exit policy
#ExitPolicy accept6 *6:119 # accept nntp ports on IPv6 only as well as default exit policy
ExitPolicy reject *:* # no exits allowed

## Bridge relays (or "bridges") are Tor relays that aren't listed in the
## main directory. Since there is no complete public list of them, even an
## ISP that filters connections to all the known Tor relays probably
## won't be able to block all the bridges. Also, websites won't treat you
## differently because they won't know you're running Tor. If you can
## be a real relay, please do; but if not, be a bridge!
#BridgeRelay 1
## By default, Tor will advertise your bridge to users through various
## mechanisms like https://bridges.torproject.org/. If you want to run
## a private bridge, for example because you'll give out your bridge
## address manually to your friends, uncomment this line:
#PublishServerDescriptor 0

After saving the file, we are ready to restart Tor:

$ sudo service tor restart

Now, we need to make sure everything worked properly and that the relay is functioning as expected. To do so, we will check the logs:

$ sudo nano /var/log/tor/log

If everything worked as expected, the following lines should appear near the bottom of the log file:

[notice] Self-testing indicates your ORPort is reachable from the outside. Excellent.
[notice] Tor has successfully opened a circuit. Looks like client functionality is working.
[notice] Self-testing indicates your DirPort is reachable from the outside. Excellent. Publishing server descriptor.

If you see anything different, make sure your torrc file is configured properly and that your firewall is set to allow connections to the ports you set for the ORPort and DirPort (by default, 9001 and 9030 respectively).

 

Monitoring Your Relay with Nyx

To monitor Tor relays, many people use a popular tool called Nyx which provides graphical information about activity and status of the node. Nyx utilizes the ControlPort we set earlier to connect into our relay. This port shot not need to be accepted by a firewall if Nyx will be running on the same machine and should be password-protected otherwise.

First, Nyx needs to be installed:

$ sudo apt-get install python-setuptools
$ sudo easy_install pip
$ sudo pip install nyx

Then,Nyx can be run:

$ nyx

The result is a nice representation of the relay’s traffic, utilization, flags, and general information.

 

Monitoring Your Relay with ARM (Deprecated)

While ARM is no longer maintained, it does still function.

To monitor Tor relays, many people use a popular tool called ARM which provides graphical information about activity and status of the node. ARM utilizes the ControlPort we set earlier to connect into our relay. This port shot not need to be accepted by a firewall if ARM will be running on the same machine and should be password-protected otherwise.

First, ARM needs to be installed:

sudo apt-get install tor-arm

Then, ARM can be run:

arm

The result is a nice representation of the relay’s traffic, utilization, flags, and general information.

 

Conclusion

While my relay picked up traffic quickly, it took a long time to be able to fully utilize the bandwidth rates that I gave it. A new Tor middle relay goes through many stages before it can be deemed stable and reliable by the network. I highly recommend reading The lifecycle of a new relay to understand the whole process and know why you may not see traffic right away.

You may notice in my screenshots of Nyx and ARM above, my relay has procured several flags. If you are trying to obtain certain flags for your relay (which sort of act like markers of the relay’s capabilities), I recommend reading this StackExchange post on the subject.

If you want to see some statistics for your relay or share them with others, consider checking out the Atlas and Globe projects. This provides information on a relay by fingerprint of that relay, though you can perform searches with the relay’s nickname. Check out my relay on Atlas and my relay on Globe for examples.

Now that your relay is functioning, you may wish to backup your torrc, backup your relay’s private key (/var/lib/tor/keys/secret_id_key), read and implement operational security practices, and join the tor-relays mailing list.

 

Sources

 

Pogo Unplugged

I got a little restless while waiting for my Raspberry Pi to get here so I decided to mess around with a few other SOCs while I wait. I was drawn to the the concept of these “plug” devices that were something of a flash in the pan a few years ago. Do you remember the SheevaPlug or the GuruPlug? Anyway, for the absent minded or unacquainted, plug computers are tiny tiny servers that run on very low power. Why keep that bulky server around when you can plug a little box into the wall, tuck it away, and forget about it for a while?

Love them or hate them, plug computers are cool little pieces of technology that are highly hackable and a good way to spend an afternoon playing with. I decided to get a Pogoplug to mess around with, as they were inexpensive when compared to some of the other plugs. They’re not the beefiest machines, but they’re not meant to be. I found a coupon that allowed me to get one at 70% off, so I took the gamble. What I got was a little NAS (which wasn’t very good at its job) with a dual core 700MHz processor and 128MB of RAM. You have to go through the hassle of registering your plug with their website to enable ssh access, but it only took five minutes and afterwards you can completely open up the hardware. With a 2GB flash drive and 20 minutes of my time, I installed Arch on my plug and then further configured it with web and IRC server software. Not bad for a cheap little box.

Pogoplug v3 Running htop

I liked the simplicity of hacking the plug and the potential it offered, so I went ahead and ordered two more.

Though the boxes have identical model numbers, the Pogoplugs I got in my second order were not the same. Apparently, my first plug was a v3, while my second two were v2s. What does that mean exactly? Pogoplugs use ARM processors. The v3 plug uses an ARMv6 while the v2 plugs use an ARMv5. So, slightly older processors but the v2s also happen to run at 1.2GHz and have 265MB of RAM. Can’t complain there.

My Pogoplugs

I found an old guide for installing Debian on a Pogoplug, and though it did not work, I followed a link to the site’s forum and was able to talk with someone to help get me going. After a painless installation, I had a second hacked Pogoplug to keep my company. Now what about the third one? Haven’t cracked into this one yet, but I have plans to try my luck with Fedora just for the variety.

What am I going to do with all these? I don’t really know. An IRC network made from just Pogoplugs sounds like fun but is completely impracticable. Any ideas?

 

Debian

So a few nights ago (I don’t remember how many because my sleep schedule is so messed up) I installed NetBSD on an old box I had lying around. This box is a P2 running at maybe 266mhz with 64mb of ram; its been a while since I’ve seen the specs, but these are roughly them. This was the second computer I have ever purchased, and has gone through so many operating systems, I can’t believe the hard disk still spins up. Win98 to Ubuntu to Debian to CentOS to- well, you get the idea.

So I got the impulse to install something new on it. I mean, I completely ignored it for a year or two, and I couldn’t remember any passwords, so an install was logical, but normally I would have just flipped the switch and forgot about it for longer. Something grabbed me. I chose to go with NetBSD because I had used flavors of Linux and Windows before, but had no experience at all with a BSD environment. So the install seems to go well, it boots, I can login, but after a while, I thought it to be lacking. Maybe a bit over my head. There was no help command, it didn’t seem to network itself; I was lost. So instead of continuing with this install, I went over it with a familiar face: Debian.

I had installed Debian for the first time maybe 2 years prior when I had absolutely zero experience. I was trying to make a web server, and needless to say, that project failed. I could always install NetBSD again later, but for now I wanted something I could use right out of the box.

The install goes smoothly, and everything settles in nicely. This time, I know the thing networked correctly because I used a bare bones net-install disc and it had to connect to the Debian ftp servers to get the additional software to accompany the core. So everything loads up, I apt-get a few more applications, screw around with making directories and whatnot, and admire my install.

After getting an sshd installed, I can now just SSH into the box from any computer on my LAN, and possibly anywhere on the internet if I ever decide to forward the port. So know, I have remote access from upstairs, and its as if I’m sitting right in front of box. The thing I really appreciate about this Debian install is being able to¬† run scripts, may they be python, perl, or my favorite: bash. This way, I can execute a whole new set of programs that I had previously been locked out of due to OS restrictions.

WOPR (Named after the Wargames movie computer) running a simple

The WOPR (Named after the Wargames computer) running a simple "Hello World" script.