MAC-Telnet @ GitHub by Ali Onur Uyar

Updates

About

Open source MAC Telnet client and server for connecting to Mikrotik RouterOS routers and Linux machines via MAC address.

Based on MAC-Telnet the original work of haakonnessjoen ( Håkon Nessjøen ); forked the upstream version to add forwarding mode for tunneling a TCP connection through MAC-Telnet protocol, and implemented MAC-SSH client and server functionality for tunneling SSH protocol instead of implementing shell interface directly.

Unless you will be using any of the additional functionalities, I recommend using the Original Version from haakonnessjoen ( Håkon Nessjøen ) instead.

For information on other projects you can check my GitHub Personal Page and GitHub Profile.

Differences

The original version implements the following:

A Linux console tool for connecting to MikroTik RouterOS devices via their Ethernet address.
Linux daemon that implements the MAC-Telnet server to permit connecting to Linux machines via their ethernet address.

The forked version implements additional functionality for forwarding a TCP connection through the MAC Telnet protocol. The main use case is connecting to Linux machines via their Ethernet address using the SSH protocol for security. Take note that the clients and servers running in the forwarding mode are not compatible with existing MAC-Telnet clients and servers implementing the standard mode of operation.

The forked version of the server supports two modes of operation: * Standard MAC-Telnet Server Mode * TCP Connection Forwarding Mode: Tunnels a TCP connection to a local port on the client to a specific local port on the server side through MAC-Telnet protocol. This mode of operation is used for forwarding SSH connections through the MAC-Telnet protocol.

The client supports three modes of operation: * Standard MAC-Telnet Client Mode * TCP Connection Forwarding Mode: Tunnels a specific local port on the client to the serverthrough MAC-Telnet protocol. * SSH Forwarding Mode: Apart from setting up the tunnel, the client takes care of launching the SSH client.

Standart MAC-Telnet Mode

[MAC-Telnet Cli] ---UDP---> [MAC-Telnet Srv]

TCP Connection Forwarding Mode

---TCP---> [MAC-Telnet Cli] ---UDP---> [MAC-Telnet Srv]---TCP--->

SSH Forwarding Mode

[SSH Cli] --->TCP---> [MAC-Telnet Cli] ---UDP---> [MAC-Telnet Srv] ---TCP---> [SSH Srv]

The SSH Forwarding Mode has the following advantages in comparison to standard MAC-Telnet:

The_mactelnet.users_ configuration file is not needed. Instead of maintaining another set of user passwords for MAC-Telnet, the authentication mechanisms implemented ssh are used.
Public Key Authentication works seamlessly permiting passwordless logins.
The communication between client and server is encrypyted by SSH.
The daemon does not require root privileges and can be run by a non-privileged user for additional security. In case the -n option is used, the server or client must be launched as root user, but the-U option can be used to drop privileges once the initial setup phase ends.
The server relies on the security model of SSH, instead of creating a shell environment itself.

Use Cases

Embedded Systems

It can be used for initial provisioning and for maintenance purposes in situations where a valid IP configuration is not available.

Might be a useful addition to the rescue mode especially of embedded systems without screens; connecting using MAC-Telnet / MAC-SSH is much more convenient then fetching and connecting a serial cable.

The Datacenter

It can be used for initial provisioning of physical and virtual servers and might serve as a rescue system, when the IP configuration of a server gets messed up for any reason.

Download

Binary Packages

The original version of the MAC-Telnet has been packaged for Debian GNU/Linux by the original author haakonnessjoen ( Håkon Nessjøen ). You can download the deb packages for the original version from the Downloads Page of the Upstream Project.

Source Packages

The original version of the MAC-Telnet by haakonnessjoen ( Håkon Nessjøen ) can be download from the project page of the Upstream Project.

You can download the latest development version of this code that is hosted at GitHub either in ZIP or TAR format.

You can also get the latest development version of the code by cloning the Git repository for the project by running:

git clone git://github.com/aouyar/MAC-Telnet

Installation

The binary packages of the original version of the code can be installed using the packaging tools of the distribution.

Once the source code is cloned or downloaded it can be installed as follows:

$ make all install

Configuration

Sample upstart configuration files can be found in the config directory of the distribution:

Use mactelnetd.init for starting / stopping MAC-Telnet in standard mode.
Use macsshd.init for starting / stopping MAC-Telnet in MAC-SSH mode.

Usage

mactelnet

Usage

$ mactelnet -h

Usage: mactelnet <MAC|identity> [-v] [-h] [-q] [-n] [-l] [-S] [-P <port>]
       [-t <timeout>] [-u <user>] [-p <pass>] [-c <path>] [-U <user>]

Parameters:
  MAC           MAC-Address of the RouterOS/mactelnetd device. Use mndp to 
                discover it.
  identity      The identity/name of your destination device. Uses MNDP 
                protocol to find it.
  -l            List/Search for routers nearby. (using MNDP)
  -n            Do not use broadcast packets. Less insecure but requires root 
                privileges.
  -t <timeout>  Amount of seconds to wait for a response on each interface.
  -u <user>     Specify username on command line.
  -p <pass>     Specify password on command line.
  -U <user>     Drop privileges by switching to user, when the command is
                run as a privileged user in conjunction with the -n option.
  -S            Use MAC-SSH instead of MAC-Telnet. (Implies -F)
                Forward SSH connection through MAC-Telnet and launch SSH client.
  -F            Forward connection through of MAC-Telnet without launching the 
                SSH Client.
  -P <port>     Local TCP port for forwarding SSH connection.
                (If not specified, port 2222 by default.)
  -c <path>     Path for ssh client executable. (Default: /usr/bin/ssh)
  -q            Quiet mode.
  -v            Print version and exit.
  -h            Print help and exit.

All arguments after '--' will be passed to the ssh client command.

Examples

Establish standard MAC-Telnet session with remote box:

$ mactelnet aa:bb:cc:dd:ee:ff

Forward local port 4001:

$ mactelnet -F -P 4001 aa:bb:cc:dd:ee:ff

Establish SSH connection with remote box:

$ mactelnet -S -u root aa:bb:cc:dd:ee:ff

Establish SSH connection with remote box, forwarding additional ports using SSH Port Forwarding:

$ mactelnet -S -u root aa:bb:cc:dd:ee:ff -- -L8080:127.0.0.1:80 -L443:127.0.0.1:8443

mactelnetd

Usage

$ mactelnetd -h

Usage: mactelnetd [-v] [-h] [-n] [-f] [-S] [-P <port>] [-U <user>]

Parameters:
  -f         Run process in foreground.
  -n         Do not use broadcast packets. Just a tad less insecure.
  -S / -F    Forwarding of TCP connections through  MAC-Telnet protocol,
             instead of using the standard MAC-Telnet remote terminal.
  -P <port>  Local TCP port used for forwarding connections to SSH Server.
             (If not specified, port 22 by default.)
  -U <user>  Drop privileges by switching to user, when the command is
             run as a privileged user in conjunction with the -n option.
             Standard MAC-Telnet is not compatible with this option.
  -v         Print version and exit.
  -h         Print help and exit.

Examples

Launch MAC-Telnet Daemon for receiving Standard MAC-Telnet protocol connections:

# mactelnetd

Launch MAC-Telnet Daemon for forwarding connections to local SSH Daemon listening on port 22:

$ mactelnetd -S

Launch MAC-Telnet Daemon for forwarding connections to local SSH Daemon listening on non-standard port 2222:

$ mactelnetd -S -p 2222

macping

Usage

$ macping -h

Usage: macping <MAC> [-h] [-f] [-c <count>] [-s <packet size>]

Parameters:
  MAC       MAC-Address of the RouterOS/mactelnetd device.
  -f        Fast mode, do not wait before sending next ping request.
  -s        Specify size of ping packet.
  -c        Number of packets to send. (0 = unlimited)
  -h        This help.

Examples

$ macping aa:bb:cc:dd:ee:ff

mndp

Usage

Usage: mndp

Examples

$ mndp

Troubleshooting

Disable firewalls both on the client and server side for testing. Firewalls can block the forwarding of packets with broadcast addresses even when they are not blocking any ports.

The server can be run in the foreground (commanline option: -f) for testing.

Credits

MAC-Telnet has originally been developed by haakonnessjoen ( Håkon Nessjøen ).

The code published on this page is a fork with some experimental features for establishing SSH connections via MAC Address. The additional features have been implemented
by Ali Onur Uyar ([aouyar @ GitHub] (https://github.com/aouyar)).

License

MAC-Telnet is copyrighted free software made available under the terms of the GPL License Version 3 or later.

See the file LICENSE that acompanies the code for full licensing information.