Despite the wide spread use of the Universal Plug-N-Play protocol in applications, operating systems and embedded devices, few tools exist that allow simple discovery and interaction with UPnP-enabled devices. Further, of the tools that do exist, most or all are closed-source Windows binaries. Miranda is a Python-based UPnP client application designed to discover, query and interact with UPnP devices, particularly Internet Gateway Devices (aka, routers).
Miranda was built on and for a Linux system and has been tested on a Linux 2.6 kernel with Python 2.5. However, since it is written in Python, most functionality *should* be available for any Python-supported platform. No special Python modules are required.
$ ./miranda.py [OPTIONS]
-s <struct file> Load previous host data from struct file
-l <log file> Log user-supplied commands to log file
-i <interface> Specify the name of the interface to use (Linux only, requires root)
-b <batch file> Process commands from a file
-u Disable show-uniq-hosts-only option
-v Enable verbose mode
-d Enable debug mode
-h Show command line help
If run with no options, you will be dropped into the interactive shell with the default settings.
| msearch | Actively locate UPnP hosts |
| pcap | Passively listen for UPnP hosts |
| host | View host list and host information |
| save | Save current host data to file |
| load | Restore previous host data from file |
| log | Logs user-supplied commands to a log file |
| head | Show/define HTTP headers |
| set | Show/define application settings |
| help | Show program help |
| quit | Exit the shell |
| exit | Exit the shell |
Many of the shell commands support various sub-commands. Miranda is designed to be as self-documenting as possible, so use '<command> help' for specific command usage, descriptions and examples.
While this tutorial will not cover every command and option available in Miranda, it will walk you through the basic usage and demonstrate the tool's major capabilities.
Upon running Miranda, you will be greeted with a 'upnp>' prompt. You will likely wish to discover all UPnP hosts on your network first; this can be done with the msearch or pcap commands. The difference is that pcap will passively listen for SSDP notification messages sent out by UPnP hosts, while msearch will actively query the network for UPnP hosts. In this example, we will use the msearch command:
upnp> msearch
Entering dicovery mode for 'upnp:rootdevice', Ctl+C to stop...
****************************************************************
SSDP reply message from 192.168.1.1:2869
XML file is located at http://192.168.1.1:2869/IGatewayDeviceDescDoc
Device is running VxWorks/5.4.2 UPnP/1.0 iGateway/1.1
****************************************************************
Discover mode halted...
Here you can see that we found one host on the network (in this case, the network's Linksys router). When run without any arguments, the msearch command will query the network for all UPnP root devices. However, if we had only been interested in UPnP hosts that are of a certian device type, or that offer a particular service, we could have queried the network for only hosts matching our criteria. For example, to search only for WANDevice UPnP devices, we could have run:
upnp> msearch device WANDevice
Likewise, if we only wanted to find hosts that support the WANIPConnection service, we could have run:
upnp> msearch service WANIPConnection
The 'host list' command will display all discovered hosts along with their host index number:
upnp> host list
[0] 192.168.1.1:2869
Since the Linksys router was the first (and in this case, only) host discovered, it has a host index number of 0. This index number will be used to reference this particular host in subsequent commands.
Before moving on, let's look at a few other host commands that we can run. At this point it is important to note that all of the 'host' commands feature full tab completion; if you're unsure of what options are available to you, or what values are in a particular piece of the host data structure, pressing TAB twice will show you.
The first command we will look at is 'host summary'; this command will display a summary of the host, along with the host's device type(s) and device info. Since we haven't enumerated any of the device types and services supported by the Linksys router, this command will only display a couple lines of information that identify the host and the location of the host's main UPnP XML file:
upnp> host summary 0
Host: 192.168.1.1:2869
XML File: http://192.168.1.1:2869/IGatewayDeviceDescDoc
Next, there is the 'host info' command that lets you walk through the entire data structure that holds information about the hosts that we've discovered. Running 'host info 0' shows the following:
upnp> host info 0
xmlFile : http://192.168.1.1:2869/IGatewayDeviceDescDoc
name : 192.168.1.1:2869
proto : http://
serverType : None
upnpServer : VxWorks/5.4.2 UPnP/1.0 iGateway/1.1
dataComplete : False
deviceList : {}
You can see that the dataComplete field is set to false, indicating that we have not enumerated any detailed information about this host. However, we do know a little bit about the host just from the results of running the msearch command, including the HTTP Server header that it is using, as indicated by the upnpServer field. Note thate the value of the deviceList field is '{}'. Any field with this value indicates that it contains data sub-sets which can be further displayed with the 'host info' command like so:
upnp> host info 0 deviceList
Because we have not discovered what type of UPnP device the Linksys router is, this command will return no data at this time.
There is also the 'host details' command that will display all devices, services, actions, arguments, etc, related to a particular host. Again, we have not discovered this information yet, and the 'host details' command tells us so:
upnp> host details 0
Can't show host info because I don't have it. Please run 'host get 0'
We'll take the 'host details' suggestion and run the 'host get' command. This command will request and parse all device and service XML files that are advertised by the host, and place the extracted data into the host data structure so that we can view it using the previously mentioned host commands:
upnp> host get 0
Requesting device and service info for 192.168.1.1:2869 (this could take a few seconds)...
Host data enumeration complete!
Now, let's try running the 'host summary' command again and see what it reports:
upnp> host summary 0
Host: 192.168.1.1:2869
XML File: http://192.168.1.1:2869/IGatewayDeviceDescDoc
WANConnectionDevice
manufacturerURL: http://www.linksys.com/
modelName: WTR54AG
UPC: IGateway-01
modelNumber: WTR54AG-01
presentationURL: None
fullName: urn:schemas-upnp-org:device:WANConnectionDevice:1
friendlyName: WANConnectionDevice1
modelURL: http://www.linksys.com/
modelDescription: WTR54AG
UDN: uuid:34bc065f-e59a-1612-9be5-c67e816b4bfb
manufacturer: Linksys
WANDevice
manufacturerURL: http://www.linksys.com/
modelName: WRT54G
UPC: IGateway-01
modelNumber: WRT54G-01
presentationURL: None
fullName: urn:schemas-upnp-org:device:WANDevice:1
friendlyName: WANDevice
modelURL: http://www.linksys.com/
modelDescription: WRT54G
UDN: uuid:28f8f50a-e59a-1612-9be4-c67e816b4bfb
manufacturer: Linksys
InternetGatewayDevice
manufacturerURL: http://www.linksys.com/
modelName: WRT54G
UPC: IGateway-01
modelNumber: WRT54G-01
presentationURL: http://192.168.1.1:80/
fullName : urn:schemas-upnp-org:device:InternetGatewayDevice:1
friendlyName: WRT54G
modelURL: http://www.linksys.com/
modelDescription: WRT54G
UDN: uuid:13814000-4ff1-11f2-9be3-c67e816b4bfb
manufacturer: Linksys
If we hadn't known that this was a Linksys device before, we do now! The router is actually advertising itself as three UPnP "devices": a WANConnectionDevice, a WANDevice, and an InternetGatewayDevice.
You can also try re-running the 'host details 0' command; for clarity and brevity, the output will not be shown here as this command will spit out everything it knows about the host and its devices/services, which at this point is quite a bit. You will probably want to save this output to disk in order to view it more easily; this can be done with the 'save info' command:
upnp> save info 0 wrt54g
Host info for '192.168.1.1:2869' saved to 'info_wrt54g.mir'
The 'wrt54g' file name is an optional argument; if it had not been supplied, then the host index number would have been used ('info_0.mir').
If you wish to save your data to share with others or to view at a later date, you can use the 'save data' command. This will save the entire host structure that contains all the information about all of the UPnP hosts that you have discovered and enumerated during your session:
upnp> save data wrt54g
Host data saved to 'struct_wrt54g.mir'
This data can later be imported back into Miranda using the 'load' command:
upnp> load struct_wrt54g.mir
Host data restored:
[0] 192.168.1.1:2869
Because this data structure is saved using Python's pickle module, any other Python script can load the file for analysis using pickle.
Let's now see if we can view the deviceList values with the 'host info' command that we tried earlier:
upnp> host info 0 deviceList
WANConnectionDevice : {}
WANDevice : {}
InternetGatewayDevice : {}
The three device types are listed here, and they have additional information that can be enumerated. You can explore the various fields and options as you like, but for brevity, we will examine only a couple of the most interesting; the first of these is the 'services' field which exists for each device listed in the deviceList. Taking a look at the services field for the WANConnectionDevice shows that it offers two services, WANIPConnection and WANEthernetLinkConfig:
upnp> host info 0 deviceList WANConnectionDevice services
WANIPConnection : {}
WANEthernetLinkConfig : {}
Each service also contains several sub-fields, but the one that we are most concerned with is the 'actions' field which shows the actions that each service supports (if this command looks too long to type, don't worry; use the tab completion!):
upnp> host info 0 deviceList WANConnectionDevice services WANIPConnection actions
AddPortMapping : {}
GetWarnDisconnectDelay : {}
GetGenericPortMappingEntry : {}
GetSpecificPortMappingEntry : {}
RequestTermination : {}
ForceTermination : {}
GetExternalIPAddress : {}
GetConnectionTypeInfo : {}
GetIdleDisconnectTime : {}
GetStatusInfo : {}
SetConnectionType : {}
DeletePortMapping : {}
GetAutoDisconnectTime : {}
RequestConnection : {}
GetNATRSIPStatus : {}
Now that we know what devices, services, and actions exist, we can start sending UPnP commands to the Linksys router. We will try running the GetExternalIPAddress action that is supported by the WANIPConnection service offered by the WANConnectionDevice device. To send commands to a UPnP host, use the 'host send' command; you must specify the host index number, the device name, the service name, and the action name, in that order. If the action requires any input values, you will be prompted for them automatically, as well as being informed of those value's type, allowed use, and default values/ranges, if any. The GetExternalIPAddress does not require any input, so it runs immediately:
upnp> host send 0 WANConnectionDevice WANIPConnection GetExternalIPAddress
NewExternalIPAddress : 69.123.45.678
The NewExternalIPAddress is the name of the output service state variable associated with the GetExternalIPAddress (some actions have several variables associated with them, but in this case there is only one), and 69.123.45.678 is the value that the UPnP host returned for that variable, which in this case is the IP address of the WAN interface.
Now let's look at a more complex request; we will attempt to forward data from port 8080 of the external WAN interface to port 80 of the router via the AddPortMapping action, essentially enabling remote administration for the router:
upnp> host send 0 WANConnectionDevice WANIPConnection AddPortMapping
Required argument:
Argument Name: NewPortMappingDescription
Data Type: string
Allowed Values: []
Set NewPortMappingDescription value to: Test Description
Required argument:
Argument Name: NewLeaseDuration
Data Type: ui4
Allowed Values: []
Set NewLeaseDuration value to: 0
Required argument:
Argument Name: NewInternalClient
Data Type: string
Allowed Values: []
Set NewInternalClient value to: 192.168.1.1
Required argument:
Argument Name: NewEnabled
Data Type: boolean
Allowed Values: []
Set NewEnabled value to: 1
Required argument:
Argument Name: NewExternalPort
Data Type: ui2
Allowed Values: []
Set NewExternalPort value to: 8080
Required argument:
Argument Name: NewRemoteHost
Data Type: string
Allowed Values: []
Set NewRemoteHost value to:
Required argument:
Argument Name: NewProtocol
Data Type: string
Allowed Values: ['TCP', 'UDP']
Set NewProtocol value to: TCP
Required argument:
Argument Name: NewInternalPort
Data Type: ui2
Allowed Values: []
Set NewInternalPort value to: 80
Note that several values were required to run this action, and that we were prompted for each one. Note that boolean values are either '1' (true) or '0' (false). By leaving the NewRemoteHost value blank, we allow any remote host to use this port mapping. Since this action does not return any values, there is no output (no news is good news).
We can verify that the port mapping was successful by invoking the GetSpecificPortMappingEntry action; this action requires that we input the external port number, external host, and protocol type of the port mapping entry we are interested in:
upnp> host send 0 WANConnectionDevice WANIPConnection GetSpecificPortMappingEntry
Required argument:
Argument Name: NewExternalPort
Data Type: ui2
Allowed Values: []
Set NewExternalPort value to: 8080
Required argument:
Argument Name: NewRemoteHost
Data Type: string
Allowed Values: []
Set NewRemoteHost value to:
Required argument:
Argument Name: NewProtocol
Data Type: string
Allowed Values: ['TCP', 'UDP']
Set NewProtocol value to: TCP
NewPortMappingDescription : Test Description
NewLeaseDuration : 0
NewInternalClient : 192.168.1.1
NewEnabled : 1
NewInternalPort : 80
Finally, we can delete this port mapping entry using the DeletePortMapping action, which requires the same input parameters as the GetSpecificPortMappingEntry action did:
upnp> host send 0 WANConnectionDevice WANIPConnection DeletePortMapping
Required argument:
Argument Name: NewProtocol
Data Type: string
Allowed Values: ['TCP', 'UDP']
Set NewProtocol value to: TCP
Required argument:
Argument Name: NewExternalPort
Data Type: ui2
Allowed Values: []
Set NewExternalPort value to: 8080
Required argument:
Argument Name: NewRemoteHost
Data Type: string
Allowed Values: []
Set NewRemoteHost value to:
Again, no news is good news, and if we try to run GetSpecificPortMappingEntry after deleting the port mapping, we get an error indicating that the port mapping no longer exists:
upnp> host send 0 WANConnectionDevice WANIPConnection GetSpecificPortMappingEntry
Required argument:
Argument Name: NewExternalPort
Data Type: ui2
Allowed Values: []
Set NewExternalPort value to: 8080
Required argument:
Argument Name: NewRemoteHost
Data Type: string
Allowed Values: []
Set NewRemoteHost value to:
Required argument:
Argument Name: NewProtocol
Data Type: string
Allowed Values: ['TCP', 'UDP']
Set NewProtocol value to: TCP
Request for 'http://192.168.1.1:2869/WANIPConnCtrlUrl' failed with error code: 500
SOAP error message: NoSuchEntryInArray
Miranda supports a batch mode, which allows you to put Miranda commands into a file that will be run sequentially. The following batch file will:
Note that the arguments to the GetSpecificPortMappingEntry are entered one per line in the batch file (including any blank lines), just as they would be if you were typing them interactively:
set max 1
msearch device InternetGatewayDevice
host get 0
host send 0 WANConnectionDevice WANIPConnection GetSpecificPortMappingEntry
8080
TCP
exit
The batch file can be loaded with the -b command line switch:
$ ./miranda.py -b batch.txt
Miranda has many other features, and is designed to be self-documenting; all of the shell commands have their own help information that detail usage and sub-commands, and provide descriptions and examples. However, the above command set comprises 99% of what you will probably want to use Miranda for, and details the steps to discover and interact with UPnP devices on your network.
Report all comments/suggestions/bugs/etc to the Miranda issues page: http://code.google.com/p/miranda-upnp/issues/list.