Should first Build before Rebrand and Make Deploy version? Or First Rebrand before Build?

[ZA]

Thank you for the detailed instructions and forum here. I ran into problems and hope to get your feedback because I believe I probably made a small mistake that had big impact on the outcome.

I spent a week reading everything and 3 days ago began creating a Deployed and Rebranded version. I am running Snow Leopard Server 10.6.8 and Xcode 3.2.2 64-bit. I have 4 GB of RAM.My goal is to create a Tunnelblick version with changed graphics and name and also includes some custom VPN configurations.

I successfully ran svn and downloaded the source code. Then I Rebranded it with the details at https://code.google.com/p/tunnelblick/wiki/cRebranding by changing info.plist and following the instructions for the other changes on that page. Then I went to build an "Unsigned Release" following the instructions at https://code.google.com/p/tunnelblick/wiki/cBuild. That was when I had problems. It was building for more than 12 hours and I finally Forced Quit Xcode and re-ran the details above for a fresh install because I worried I made a mistake. Then I did everything again and this time I let it build for more than 18 hours before force quitting.

Then I decided to **not**  Rebrand it yet and instead just Build first. This was successful and it took only about 15 minutes to have a "Build Succeeded" message with 193 Warnings.

So my question is: to make a Deployed and Rebranded version I should first "Build" correct? If so, can I Build again after I Rebrand? I have not tried that yet but first seek your advice so I don't miss so many more hours :)

[jkbull...gmail.com]

Hmmm. I don't see why it would make a difference. But you certainly should be able to rebrand after building, though -- I sometimes do that.

Use the following menu commands:

1. Build | Clean All Targets (If I recall correctly, this avoids some warnings from Xcode)
   
2. Build | Build (This will take a long time (45 minutes for me) because it builds the third-party software as well as Tunnelblick)
   
3. (Do the rebranding)
   
4. Build | Clean All Targets (Doesn't clean the third-party software, which isn't rebranded).
   
5. Build | Build This will be pretty quick (5 minutes for me) because the third-party software is not being rebuilt)

Xcode has a "Build Results" window (Build | Build Results) that shows exactly what is going on -- set it to show "Latest Results" and "By Stop" and "Errors & Warnings Only" and you should see a steady stream of messages about the progress of the build. (This window is over 16,000 lines long when the build is complete.)

I haven't updated the instructions for rebranding or building for a while (I just put that on my to-do list), so there are two minor changes: when you rebrand there are more like 10,000 or 12,000 places where Tunnelblick needs to change to (whatever), and recent versions of OpenVPN generate 64 warnings each, for a total of about 192 warnings for the three versions included in the current source code. (The warnings can be ignored; I forget what the 193rd one is, but you can ignore that, too.)

Tunnelblick is built in two pieces -- the third-party piece and the Tunnelblick piece. (You don't do anything special to make the two pieces -- they are both built automatically when you build Tunnelblick.)

The third-party piece is usually much slower, especially if there are several versions of OpenVPN being built. On my single-CPU, 4 GB virtual machine running Snow Leopard Server, it takes about 45 minutes or so -- the host is a MacBook Pro with a 2.3 GHz Intel Core i5 running Mountain Lion.

The Tunnelblick build is much quicker -- 5 minutes or less.

When you "Clean" Tunnelblick, it only cleans the Tunnelblick part. That's on purpose to speed up builds, because the third-party part rarely changes.

One other note: If you are going to sign the app, you should sign it under Mountain Lion. If you sign it under any other version of OS X, the signatures will not work on some other versions of OS X.

Good luck!

[ZA]

Thanks for your advice. Ok so I shall folow your 5 steps on the menu commands to make this. First Build (steps 1-2), and then Rebrand (step 3), and then Build again (steps 4-5).

I did that and found the tunnelblick-read-only/tunnelblick/build/Release/Tunnelblick.dmg missing. The /Release/ directory was empty. However, I did find this: tunnelblick-read-only/tunnelblick/build/Unsigned Release/NAMEOFPROJECT.dmg. That is the correct dmg I should be using since it is an Unsigned Release correct?

[jkbull...gmail.com]

Yes, when you create an "Unsigned Release", Xcode puts everything into the tunnelblick-read-only/tunnelblick/build/Unsigned Release folder.

(Also, the "read-only" confused me the first time I saw it years ago. It isn't really "read-only"; it just means that the source code can't be modified and then fed back into the Subversion version control system that Tunnelblick uses. Nothing to do with read-only files or anything like that.)

The idea of the rebranding is that everywhere the user usually sees "Tunnelblick", they will see "NAMEOFPROJECT". That will cause the .dmg to be named differently, too.

However, everywhere you see "tunnelblick", it will stay "tunnelblick". That is OK, since it isn't visible to the user. For example, the icon in NAMEOFPROJECT.app/Contents/Resources is still named "tunnelblick.icns". You should replace it with your own .icns file with your own icons, but keep the "tunnelblick.icns" name.

The …Resources/IconSets file will still contain folders with the "Tunnelblick name". You will be replacing the images in them, but keep the folder names; Tunnelblick will use localized names for the names of the folders. The one file you may want to remove or rename is the "3.3.TBMenuIcons" folder (and the corresponding "large-…" folder).

Basically, you should not change the names of files or folders manually; the rebranding process will change the names of files and folders that need to have their names changed.

----------

I mentioned that the app signing must be done on Mountain Lion; I should have said it should be done on version 10.8.3 or higher (I use 10.8.5) because only 10.8.3 and higher can sign the kexts for Mavericks.

An "Unsigned Release" build's …Resources/ folder will contain three TUN kexts (and three corresponding TAP kexts). The only kexts that should be signed are "tun-signed.kext" and "tap-signed.kext". Tunnelblick will use them only on Mavericks because their use on older versions of OS X is problematic. Earlier versions of OS X use the unsigned kexts.

The last time I checked, Mavericks accepted unsigned Tunnelblick kexts. (It seems to include Tunnelblick's kexts on some kind of whitelist.) However, for "future-proofing", official Tunnelblick releases contain the signed kexts, too, and use them on Mavericks -- some future update of Mavericks may require signed kexts and I don't want everyone's Tunnelblick to stop working if that happens.

The entire signing process is painful and full of pitfalls; Apple has made it really difficult to create a program that works on several versions of OS X.

[ZA]

Ok this makes sense about some of the information becasue I see some may be outdated here and there but it is easy to relaize what to do in most situations. However I am confused about this one area at the top of https://code.google.com/p/tunnelblick/wiki/cCusDeployed it says:

Each configuration in /Deploy must be a Tunnelblick VPN Configuration (".tblk"), and must be structured as described in the Format section of the ".tblk" Details page.

But down below on that page in the "What is Needed to Make a Deployed Version" section it says:

Optional: one or more OpenVPN configuration files, with extensions of ".ovpn" or ".conf".

So my question is can we just place the .crt and .ovpn files directly into the Deploy folder, or should they instead now be .tblk type files? Or should they always be tblk files but the addition of the ovpn is "optional"?

[jkbull...gmail.com]

Sorry for the contradictory documentation.

The contents of Deploy should be .tblk "packages" [1], not .ovpn or .conf files.

They should be in the "standardized" format -- the format a .tblk has after it has been installed by double-clicking it. That's the format where XXX.tblk contains a folder named Contents, which may contain an Info.plist file, and which contains a folder named Resources, which contains all the files for the configuration. The Resources folder must contain a file named config.ovpn, which is the configuration file. (The other files are optional and would be .key, .cert, .sh, etc. files that are associated with the configuration.)

They are optional, in that you can make a useful Deploy folder with no configurations (it would only have a forced-preferences.plist file). But that's probably not what most people want to do.

There's a (relatively) easy way to make .tblk packages from a set of .ovpn/.conf files and their associated files. It's great if you have, for example, 20 .ovpn files that share a .key or .cert files:

1. Quit Tunnelblick
   
2. Rename ~/Library/Application Support/Tunnelblick/Configurations to be Configurations.OLD -- NOTE THE "~" AT THE START OF THE PATH [2]
   
3. Create an empty folder at  ~/Library/Application Support/Tunnelblick/Configurations
   
4. Put all the OpenVPN .conf/.ovpn (doesn't matter which from Tunnelblick's perspective) and other files into that newly-created empty folder
   
5. Launch Tunnelblick.
   
6. You'll be asked if you want to convert the configurations to Tunnelblick VPN Configurations -- convert them.
   
7. Quit Tunnelblick after the (successful) conversion.
8. Rename ~/Library/Application Support/Tunnelblick/Configurations to be Deploy
9. Rename ~/Library/Application Support/Tunnelblick/Configurations.OLD to be just plain Configurations
10. Move ~/Library/Application Support/Tunnelblick/Deploy to your Desktop (or wherever you want) -- it is the "Deploy" folder that you will put in NEWPROJECT.app/Contents/Resources

However, the error messages for this process are not very clear. You might want to do some initial testing by making a .tblk manually and installing it by double-clicking. That will give much more informative error messages if there are problems. Once you figure out what files are needed, you can 

[1] OS X "packages" are really folders, but have an extension that is registered with OS X as belonging to a particular program. Tunnelblick registers ".tblk". Most of OS X (e,g, Finder) treats the folder as if it were a file, but in Terminal you can see that it is just a folder and you treat it as a folder.

[2] The "~" at the start of the paths indicates that it is /Users/NAME/Library... (where XXX is your OS X short username), not /Library...

Recent versions of OS X make it difficult to get to the /Users/NAME/Library folder in Finder -- usually you can hold the "Option" key as you click the Finder's "Go" menu command and see "Library" as one of the options, that "Library" is actually /Users/NAME/Library, which is the one you want.

[ZA]

Thank you for info about tblk and this makes sense and is easy to make the tblk with your method.

We are trying to decipher different texts on the instructions so need your advice. We created a Code Signing certificate with Keychain Access on 10.8.5. But now we should use the Xcode on 10.8.5 (Xcode version 5.1.1) to re-Build the Unsigned Release of Tunnelblick with the new Code Signing certificate? Or should we move that cert back to Snow Leopard Server and rebuild on Xcode 3.2.2 but this time change it to a "Signed Release"?

Tkx for your advice

[jkbull...gmail.com]

Code signing is a huge mess on OS X. The problem is creating signatures that work on 10.5 (when it was introduced) through 10.9 (the latest so far). If you don't need to have a single binary that works on all those versions of OS X (Tunnelblick also works on 10.4, which ignores signatures), you may have an easier time than I did.

And another possibility is for you to ignore signatures altogether, and use an unsigned version of your rebranded Tunnelblick. If you do that, you may want to include an entry with a key of "skipWarningAboutNoSignature" and a value of "true" in the "forced-preferences.plist" in your Deploy folder. (But see my note at the end of this post about using Tunnelblick's signed kexts on Mavericks.)

The application itself must be signed, of course, but so should the kexts that run on Mavericks ("tap-signed.kext" and "tun-signed.kext"). Tunnelblick uses them on  Mavericks only, because the signatures cause them not to work on anything lower than Mavericks. The other two pairs of kexts are used on non-Mavericks versions of OS X, which pair depends on which version of OS X is running. Even though in theory Mavericks requires signed kexts, the last time I checked (months ago), Mavericks allowed the unsigned Tunnelblick kexts to be used, apparently because of a special-case whitelist built into Mavericks. But I am concerned that they could withdraw that at any time (for example, in a point release of 10.9) making the kexts suddenly unusable. So I made sure Tunnelblick has signed kexts. In addition to the two Mavericks kexts, Tunnelblick also signs:

atsystemstart

installer

openvpnstart

process-network-changes

standardize-scutil-output

the openvpn and openvpn-down-root.so binaries for each version of OpenVPN that is included

the Sparkle framework

 

and then the application itself (after everything else has been signed). The uninstaller application is also signed, which replaces the (unusable on some versions of OS X?) signature that is created automatically by the procedure that creates the uninstaller.

 

You need both the signing key/certificate and a "requirements binary". I don't remember how I created the requirements binary; I followed some instructions on the web. The signing key/certificate is from Apple; my understanding is that they are a special "kext" signing key/certificate that can be used to sign kexts for use in Mavericks, but I could be wrong. Apple was very cagey about getting the certificates -- I had to give them an explanation of why I needed to sign kexts. That was before Mavericks was released, though, and it could have had something to do with it being done under the non-disclosure agreement in force at the time.

I hope this helps. My advice is to skip signing completely, and copy the signed kexts from Tunnelblick into your your rebranded version of Tunnelblick. That should work, and is what several VPN service providers do.