Uproot(uprt
) is a multi-platform (Windows, MacOs, and Linux) command line utility written in Dart to convert a router's DHCP IP Reservations between routers. DHCP Reservations are also sometimes referred to as static mappings (and throughout this documentation they are typically referred to as static leases).
For example, uprt
can be used to help move static leases from DD-Wrt to OpenWrt, or from OpenWrt to pfSense, or back and forth between various other router formats. Uprt
avoids errors on import by verifying and enforcing required network ranges, eliminating duplicate leases, and validating Ip and Mac addresses.
In addition, uprt
can merge existing lists of static leases using the merge
command.
ip6 static leases are not supported.
Download Windows, Mac, and X86 Linux binaries
Like this project ? Please click the star at the top right corner of this page.
Many network administrators often have long lists of DHCP reservations specified in their router. Those who do a lot of home automation, for example may have many devices for which IPs have been statically assigned, making upgrading to a different type of router painful. Many times the IP reservations along with the associated Mac Addresses need to be manually re-entered into the new router's software. As long as the router formats are supported, Uproot allows one to export the list of DHCP Reservations from one router, and easily convert the list to a format of another supported type. In addition to straight import, Uproot can merge and validate the static leases from both the old and the new router, eliminating duplicates.
Also supports the following file formats:
If you have a target device that is supported, but an unsupported source device (e.g., you are migrating from Google Wifi to OpenWrt), see Unsupported Routers - Creating A CSV File of Network Devices Using Nmap.
rsc
files are generated without hostnames)Binaries are included for macOS, Linux, and Windows for the latest releases. Simply download to your respective platform and put in your path.
If you choose to compile yourself:
Open a terminal.
Install the latest version of Dart for your operating system.
Clone the repository (you'll need a personal access token if by https).
Example:
git clone https://github.com/GeekVisit/uproot.git
Pull down the dependencies:
cd uproot
dart pub get
Run all tests (optional):
dart test
Change into the bin directory and compile:
cd bin
dart compile exe uprt.dart -o uprt [or -o uprt.exe on windows]
If on Linux or Mac, set permission and copy into bin directory in path:
sudo chmod 700 ./uprt
sudo cp ./uprt /usr/local/bin/uprt
sudo chown $(whoami) /usr/local/bin/uprt
If on Windows, make sure uprt.exe
is in a folder that is in your PATH environmental variable. If not, move it to the appropriate path or add the directory.
Test the binary with included test files:
cd .. [so you are in the uproot folder]
uprt test/test-data/lease-list-infile.csv -g cdjmnop -d test/test-output
For a complete list of options, type uprt
or uprt -h
Below is the latest help:
uprt (2021.10.001 running on macos 10.15.7)
A tool to migrate static leases between DD-WRT, OpenWrt, OPNsense, Mikrotik, and pfSense routers. Also supports csv and json.
Usage:
-a, --append Used when --merge and --sort are given. If this flag is given, the merged file
will have the sorted leases from the source file appended to the end of the
target file leases rather than integrated with the merge file.
-b, --base-name Specify Base Name of Output Files (default uses basename of input file)
-d, --directory-out Directory to write files to, defaults to same directory as input file.
-h, --help Help
-t, --input-type Input file type: c (csv), d (ddwrt), j (json),
m (Mikrotik RouterOS), n (OPNsense), o (OpenWrt), p (pfsense)
If this option is not used, uprt will try to determine file
type based on the following extensions: .csv, .ddwrt,
.json, .rsc (mikrotik), .xml (for opnsense and pfsense,
distinguishing by searching for <opnsense> in file)
-g, --generate-type Required. Generated types may be multiple. Valid values include:
c (csv), d (DD-WRT), j (json),
m (Mikrotik RouterOS), n (OPNsense), o (OpenWrt), p (pfsense)
-L, --ip-low-address Enforced Lowest Ip of Network Range, Excludes Addresses Lower Than This From Target File
-H, --ip-high-address Enforced Highest Ip of Network Range, Excludes Addresses Higher Than This From Target File
-l, --log Creates Log file, if -P not set, then location is in temp folder
-P, --log-file-path Full file path to log file.
-m, --merge Merge to file. Specify path to file to merge converted output.
Used to add static leases to an existing output file.
-S, --server Name to designate in output file for Mikrotik dhcp server.
(defaults to "defconf")
-r, --replace-duplicates-in-merge-file Applies only when using --merge. If this option is set and the source file
has a static lease which has the same mac address, ip or hostname as a lease in
the merge file, the lease or leases in the merge file that have any of the
duplicate components will be discarded and the input lease will be used.
By default, this is set to false so any lease in the input file that has the
same ip, hostname, or mac address as one in the merge file is discarded.
-s, --[no-]sort Leases in resulting output file are sorted by Ip address.
(defaults to on)
-v, --verbose Verbosity - additional messages
-z, --verbose-debug Verbosity - debug level verbosity
-V, --version Gives Version
-w, --write-over Overwrites output files, if left out, will not overwrite
Examples:
Convert a csv file to all formats (csv, json, DD-WRT, Mikrotik, OpenWrt, OPNsense, pfSense):
uprt test/test-data/lease-list-infile.csv -g cdjmnop -d test/test-output
Convert multiple csv files to PfSense and save output to a specified directory:
uprt test/test-data/*.csv -g p -d test/test-output
Convert a csv file to all formats, stripping out leases not in range and saving output to specified directory:
uprt test/test-data/lease-list-infile.csv -g cdjmnop -L 192.168.0.1 -H 192.168.0.254 -d test/test-output
Merging leases in a CSV file with an existing DDWRT file and generating an OpnSense file:
uprt test/test-data/lease-list-infile.csv -m test/test-merge/lease-list-infile-merge.ddwrt -g n -b example-merge-output -d test/test-output
Make a full backup of your router/firewall before importing any files generated by uprt. Use of uprt and files generated by uprt is entirely at user's risk.
To test uprt yourself, there are test input files are located under the test/test-data
folder in the repository. Cd into the uproot directory and apply the examples given in uprt -h
on the test files.
Below is a demonstration done on Mac Catalina showing the conversion from a .csv file to all formats. After the conversion the demo scrolls through the resulting files.
To use Uproot, you'll need to export and import static leases to the respective routers.
Below are the export/import steps for each router/firewall type that is supported by Uproot.
The following router and firewall software are supported:
If you have a target device that is supported, but an unsupported source device (e.g., you are migrating from Google Wifi to OpenWrt), see Unsupported Routers - Creating A CSV File of Network Devices Using Nmap.
Ssh into your router and enter the following on the command line to export static leases to a file:
nvram get static_leases > static_leases.ddwrt
Download the static_lease.ddwrt
file from the router by using WinScp or a similar utility. If you do use WinScp, use the SCP protocol.
Alternatively you can simply execute nvram get static_leases
and copy the output from the terminal, paste it into a text file and save it locally.
Now use the exported file as an input file to Uproot and convert to your required format.
Example:
Converting from DD-WRT format to OpenWrt format, with static leases having range of 192.168.0.1 to 192.168.0.254:
uprt static_leases.ddwrt -g o -L 192.168.0.1 -H 192.168.0.254
NOTE: Always Make a backup of your DD-WRT software configuration before importing (via backup tab in the Web interface). All imports will REPLACE your existing static leases. To add leases to an existing file, use the --merge option
. **
Using WinSCP (if on Windows) or a similar utility, login to your router and upload the static_leases.ddwrt
file to the router.
Using Putty if on Windows, or other ssh command line client, type the following, and press Enter
,replacing "X" with the number of static leases you are importing.
nvram set static_leasenum=X
Type the following and press Enter
. Note that the quotes are important:
nvram set static_leases="$(cat static_leases.ddwrt)"
nvram commit
Reboot the router. Your static leases should appear under the Services
tab in the browser interface.
TIP: If you have any issues with the above, log in using your browser to your router and view the changes as you make them. For instance, you can click on the Services
tab and view the static leases after you set the nvram variable. If the nvram commit
doesn't work try clicking "Save" and then "Apply Settings" in the browser interface.
Using Putty if on Windows, or other ssh command line client, log into your router and type the following which will extract the static leases to a separate file for download:
grep -hnr -A3 "config host" /etc/config/dhcp > static_leases.openwrt
If this gives an error (e.g., if your version of OpenWrt does not have grep installed), just use copy (uprt
will still be able to ignore the extra configuration information and extract the lease information from the raw dhcp file):
cp /etc/config/dhcp static_leases.openwrt
Verify that the resulting file contains the static lease information:
cat static_leases.openwrt
Using scp or WinScp if on Windows, download the static_leases.openwrt
file.
Use the exported file as an input file to Uproot and convert to your required format.
Examples:
Converting DD-WRT to a json file
uprt static_leases.ddwrt -g j -L 192.168.0.1 -H 192.168.0.254
Converting DD-WRT to a Mikrotik RouterOS import script
uprt static_leases.ddwrt -g m -L 192.168.0.1 -H 192.168.0.254 -s defconf
NOTE: Always Make a backup of your Openwrt Router Files before importing! All imports will REPLACE your existing static leases. To add leases to an existing file, use the --merge option.
Using WinSCP (if on Windows) or a similar scp utility, login to your router and upload the file to be imported to the router (static_leases.openwrt
in the Open-WRT export example).
Using Putty or other ssh command line client, enter the following two lines:
cp /etc/config/dhcp /etc/config/dhcp.original
cat *infile.openwrt >> /etc/config/dhcp
WARNING: Be sure that there are two >>
, otherwise the dhcp file will be overwritten instead of appended. Thus the recommended backup! To merge [will remove duplicates] instead of append, see step 4.
ALTERNATIVELY, you can download the dhcp
file to your local computer, merge the import file using uprt
, then upload the resulting dhcp.openwrt
file with the resulting merged file (you'll need to rename the output file to dhcp
). The advantage of this is you'll be able to sort the static leases by IP address and uprt
will also automatically take care of duplicates (please see uprt -h
for sorting and append options). Example:
On local computer:
uprt infile.openwrt -g o -m dhcp -b dhcp
Upload dhcp.openwrt to your router, remove the "openwrt" and replace /etc/config/dhcp.
cp /etc/config/dhcp /etc/config/dhcp.original
cp /etc/config/dhcp.openwrt /etc/config/dhcp
Reboot the router. Your static leases should appear under the Services
tab in the browser interface.
TIP: If you have any issues with the above, login using your browser to your router. Static leases should appear in Network->DHCP and DNS->Static Lease
. If you don't see the imported leases, repeat steps, viewing the browser window as you make them. After the static leases appear, click Save & Apply
on theDHCP and DNS
web page.
Log in to your OPNsense router and navigate to System->Configuration->Backups.
Click on the big "Download configuration" button and download the file.
The backup file you've downloaded contains ALL backup data for the router. As of this writing, the OPNSense configuration does not allow partial backups of data (although it does allow partial restores). Since you only need the data in the static map tags and their parents and related closing tags, you can delete all tags unrelated to the static lease export. Preserve the static map tags and the other tags shown in the below example, but delete all others:
Use the exported file as an input file to Uproot and convert to your required format.
Example:
Converting OPNSense to pfSense
uprt static_leases-opn.xml -g p -L 192.168.0.1 -H 192.168.0.254
NOTE: Always make a backup of your OPNsense configuration before importing !
Importing REPLACES any static leases your router currently has. If you are adding leases to an existing configuration, follow these steps for merging .
To start your import, log in to your OPNsense router and navigate to System->Configuration->Backups.
Click on the big "Download configuration" button and download the file.
In the Restore
section under the Restore Area
click on the drop down arrow and change All
to DHCP Server
. Click on Browse ...
and select the file to be imported. Then click "Restore configuration".
OPNSense should respond with a "Successful" message.
To view the imported leases, navigate to Services->DHCPv4->[LAN].
Scroll down and verify the static leases have been imported.
If you are ADDING leases to an existing OpnSense configuration, you'll need to use the --merge
option, merging the import file into a backup file of your existing configuration. Download to your local computer a backup from your existing configuration, then merge with the file to be imported:
uprt static_leases-to-import-opn.xml -m static-lease-backup.xml -g o -b merge-output
This will output a "merge-output-opn.xml" file. Import this into your OpnSense router.
Log into pfSense using your browser and navigate to Diagnostics->Backup & Restore:
Scroll down to Backup Configuration
and set Backup area
to DHCP Server
. Click Download configuration as XML
.
Use the exported file as an input file to Uproot and convert to your required format.
Example
Convert pfSense to OPNsense:
uprt static_leases-pfs.xml -g p -L 192.168.0.1 -H 192.168.0.254
NOTE: Always make a backup of your pfSense configuration before importing !
Importing REPLACES any static leases you currently have. If you are adding leases to an existing configuration, follow these steps for merging .
Log into pfSense using your browser and navigate to Diagnostics->Backup & Restore:
In the Restore
section under the Restore Area
click on the drop down arrow and change All
to DHCP Server
.
Click on `Browse ..." and select the file to be imported. Then click "Restore Configuration".
pfSense should respond with a "The configuration area has been restored. The firewall may need to be rebooted."
To verify the leases have been imported, navigate to Services->DHCP Server. Click on the LAN tab and scroll down to the "DHCP Static Mappings for this Interface" section where your imported leases should appear:
If you are ADDING leases to an existing pfSense configuration, you'll need to use the --merge
option, merging the import file into a backup file of your existing configuration.
Download to your local computer a backup from your existing configuration, then merge with the file to be imported:
uprt static_leases-to-import-pfs.xml -m static-lease-backup.xml -g p -b merge-output
This will output a "merge-output-pfs.xml" file. Import this file into your pfSense router.
Open New Terminal
from the menu in Winbox, or in Webfig click on the Terminal
button on the top.
Execute the following:
/ip dhcp-server lease export file=dhcp-static-leases.rsc
This exports a file called "dhcp-static-leases.rsc" which will appear in Files
.
)
Click on the Files
menu item.
)
Download the dhcp-static-leases.rsc
to your computer.
Use the exported file as an input file to Uproot and convert to your required format.
Example: Convert Mikrotik RouterOS file to pfSense
uprt dhcp-static_leases.rsc -g p -L 192.168.0.1 -H 192.168.0.254
Select Files
from the menu and upload your input file (or just drag and drop your file if using Winbox).
Open New Terminal
from the menu in Winbox, or in Webfig click on the Terminal
button on the top.
Execute the following, changing the name of the input file as needed:
/import file=dhcp-static-leases.rsc
The terminal should respond "Script file loaded and executed successfully".
Common Error Messages:
--merge
option - see above.**Verify all leases are imported by navigating to IP->DHCP Server and clicking the Leases
tab.
Or, alternatively, by using the terminal:
/ip dhcp-server lease print
If you are ADDING leases to an existing Mikrotik configuration, you'll want to use the --merge
option, merging the import file into a backup file of your existing configuration.
Download to your local computer a backup from your existing configuration, then merge with the file to be imported:
uprt dhcp-static-leases.rsc -m dhcp-static-leases-export.rsc -g m -b merge-output
This will output a "merge-output.rsc" file. Upload the file to your Mikrotik router and follow the steps for importing.
If Uproot does not support your existing router and you wish to generate a list of the devices on your network to be used as a source file for uprt
, you can use nmap and awk
to generate a CSV file containing all online devices. You will need to edit the file to delete any devices you don't want to assign a static lease, or add any devices which were offline during the scan.
Install nmap and awk if not already installed.
Open a terminal and check if nmap
is installed, if not install.
Do the same for awk
. awk
is usually installed by default for Mac and Linux. gawk
will work.
To install awk
on Windows, if you have chocolatey installed, at an Administrator command prompt, enter choco install nmap
and choco install gawk
. If you aren't using chocolatey, download and install nmap and awk.
The following command will generate the CSV file ip_list.csv
containing the leases of your online devices. The versions for the different operating systems differ slightly.
Windows :
nmap -sn X.X.X.X/X| awk "BEGIN { printf \"host-name,mac-address,address\n\";}/Nmap scan report for/{host = (NF == 6) ? $5 : \"\"; ip = (NF==6) ? $6 : $5; gsub(/\(/,\"\",ip);gsub(/\)/,\"\",ip);}/MAC Address:/{mac=$3; printf host\",\"mac\",\"ip\"\n\";}" > ip_list.csv
Linux and Mac :
sudo nmap -sn X.X.X.X/X| awk 'BEGIN { printf "host-name,mac-address,address\r\n";}/Nmap scan report for/{host = (NF == 6) ? $5 : ""; ip = (NF==6) ? $6 : $5; gsub(/\(/,"",ip); gsub(/\)/,"",ip);}/MAC Address:/{mac=$3; printf host","mac","ip"\n";}' > ip_list.csv
Replace "X.X.X.X/X" with your network's gateway and applicable CIDR (e.g., 192.168.1.1/24 if your network gateway is 192.168.1.1 using the typical home network CIDR of 24).
On Linux and Mac you must use sudo
. Otherwise nmap
will not be able to detect the mac addresses. The only difference between the above two statements, other than the removal of sudo
for Windows is the different use of quotations. Windows requires quotes to be escaped and double quotes surrounding the awk
statement.
A static lease or DHCP Reservation forces your router to assign the same IP address to a particular device on the network. By default, your router's DHCP server will dynamically assign IP addresses randomly to your network devices. By reserving an IP address for a particular device (e.g., 192.168.0.10 for a Raspberry Pi running piHole) the DHCP server is reserving a specified IP address for that device only, resulting in the same lease being assigned each time the device comes online (so such lease is static rather than dynamic), making it much easier for other devices to communicate with it. This can be particularly helpful for configuring home automation devices or setting up port forwarding.