node-tuntap2

a opensource, asynchronized, napi-based, business friendly tuntap device driver addon for nodejs.

TL; DR

const {Tun, Tap} = require('tuntap2');

try {
    const tun = new Tun();
    tun.mtu = 1400;
    tun.ipv4 = '10.0.0.100/24';
    tun.ipv6 = 'abcd:1:2:3::/64';
    tun.on('data', (buf) => {
        console.log('received:', buf);
    })
    tun.isUp = true;
    console.log(`created tun: ${tun.name}, ip: ${tun.ipv4}, ${tun.ipv6}, mtu: ${tun.mtu}`);
    tun.release();

}
catch(e) {
	console.log('error: ', e);
	process.exit(0);
}

install

npm i tuntap2

Properties

interface TuntapI extends Duplex {
    /**
     * the name of this tun/tap device. 
     * This will be generated.
     * @type {string}
     * @memberof TuntapI
     * @since 0.0.1
     */
    readonly name: string;
    /**
     * returns `true` if this is a Tap device
     * @type {boolean}
     * @memberof TuntapI
     * @since 0.0.1
     */
    readonly isTap: boolean;
    /**
     * returns `true` if this is a Tun device
     * @type {boolean}
     * @memberof TuntapI
     * @since 0.0.1
     */
    readonly isTun: boolean;
    /**
     * the mac address of this interface
     * @example
     * ```js
     * this.mac = '00:11:22:33:44:55';
     * ```
     * @type {string}
     * @memberof TuntapI
     * @since 0.1.1
     */
    mac: string;
    /**
     * mtu of this interface
     * @example
     * ```js
     * this.mtu = 1500;
     * ```
     * @type {number}
     * @memberof TuntapI
     * @since 0.0.1
     */
    mtu: number;
    /**
     * ipv4 address/subnet in cidr format of this interface
     * @example
     * ```js
     * this.ipv4='127.0.0.1/24';
     * ```
     * @type {string}
     * @memberof TuntapI
     * @since 0.0.1
     */
    ipv4: string;
    /**
     * ipv6 address/subnet in cidr format of this interface
     * @example
     * ```js
     * this.ipv6='abcd:0:1::/64';
     * ```
     * @type {string}
     * @memberof TuntapI
     * @since 0.0.1
     */
    ipv6: string;
    /**
     * get/set the interface to up/down status
     * @example
     * ```js
     * this.isUp = true; //set this interface up
     * ```
     * @type {boolean}
     * @memberof TuntapI
     * @since 0.0.1
     */
    isUp: boolean;
    /**
     * release this interface
     * @memberof TuntapI
     */
    release: ()=>void;
}

Note: Reading properties requires your interface in up status.

Note: For a Tun device, mac property is readonly.

Node: Please make sure the first 8bits is 00 for setting the mac address of a Tap device.

Streams API

The tuntap object supports Node.js Duplex interface. However, almost all streams api methods is a wrapper of fs.ReadStream or fs.WriteStream. The writing and events are based on them.

Performance

The writing and reading of tuntap is based on nodejs fs and readingStream. This means these methods is running on libuv threads pool. Please set the threads pool size properly for your application.

Test

npm test

Contribute

Please feel free to create issues, Prs and tell me your ideas!

I REALLY APPRECIATE IT

TODO

• add BSD os support
• add tap devices support for osx, using utun.
• add demos