--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/releasing/cbrtools/perl/ExportingReleases	Fri Jun 25 18:37:20 2010 +0800
@@ -0,0 +1,215 @@
+#!perl
+# Copyright (c) 2000-2009 Nokia Corporation and/or its subsidiary(-ies).
+# All rights reserved.
+# This component and the accompanying materials are made available
+# under the terms of the License "Eclipse Public License v1.0"
+# which accompanies this distribution, and is available
+# at the URL "http://www.eclipse.org/legal/epl-v10.html".
+# 
+# Initial Contributors:
+# Nokia Corporation - initial contribution.
+# 
+# Contributors:
+# 
+# Description:
+# 
+#
+
+=head1 Introduction
+
+When a release is created with C<makerel> and C<makeenv> it is stored in the releasers local archive. To share this release with other development teams involved in the project it must be exported to a remote release archive (typically hosted on an FTP server) which all teams have access to. 
+
+This document describes how to configure and use the tools to export a teams releases to the remote archive and import other teams releases from it.
+
+=head1 Configuration
+
+The F<reltools.ini> and export data files must be set up as described in the F<Installation> document. Typically these files will have already been created for the user so no further editing of them is required. (An archive path file may also be needed, depending on your archive arrangement).
+
+Releases exported to the remote site are PGP encrypted for security. To encrypt and decrypt releases a command line PGP tool is used by the tools (defined by the C<pgp_tool> keyword in the F<reltools.ini> file). Both supported PGP clients (GnuPG and NAI PGP) require some configuration before they will work with the tools. 
+
+=head2 Configuring Network Associates PGP
+
+NAI command line PGP (version 6 or 7) must be installed on the users machine. The executable is assumed to have the name C<pgp.exe> and exist somewhere in the users path.
+
+PGP encrypts and decrypts files using keys stored on a public and secret key ring. Before using the export and import tools the user must set up their key rings for the project they are working on. If pre-configured keyrings have not been supplied the steps below should be followed:
+
+=over 4
+
+=item * 
+
+To use keys from another keyring first extract the keys with the command
+
+ pgp -kx <keyid> keyfile
+
+If the keyrings are not stored in the default directory then the options C<+PUBRING> or C<+SECRING> are required. For example
+
+ pgp +PUBRING=keyringPath/pubring.pkr -kx 0x12345678 foo.asc
+ pgp +SECRING=keyringPath/secring.skr -kx 0x87654321 bar.asc
+
+Remember to extract both public and private keys.
+
+To extract keys using the GUI version of PGP use the export key menu option. If the key is private make sure the "include private keys" check box is selected.
+
+=item *
+
+Create empty key ring files F<pubring.pkr> and F<secring.skr>. Add key files to these key rings using the command
+
+ pgp -ka keyfile  
+
+For example
+
+ pgp +PUBRING=keyringPath/pubring.pkr -ka somePublicKeyfile.asc
+ pgp +SECRING=keyringPath/secring.skr -ka someSecretKeyfile.asc
+
+The project key rings must have the names F<pubring.pkr> and F<secring.skr> but can be stored in any directory. If this is not the default directory used by PGP then the user must set the C<pgp_config_path> keyword in the F<reltools.ini> file to the directory where they are stored.
+
+=item *
+
+Check that the keys exist on the key ring using the command
+
+ pgp -kv
+
+For example
+
+ pgp +PUBRING=keyringPath/pubring.pkr -kv
+ pgp +SECRING=keyringPath/secring.skr -kv
+
+=back
+
+Once the keyrings have been created and populated, the keys must be signed with the users private key so that PGP can encrypt non-interactively (a requirement for the export tools to work). To sign all the keys on the project keyring follow the steps below:
+
+=over 4
+
+=item *
+
+First set the users private key to be the most trusted introducer and the default signing key. To do this run the command
+
+ pgp -ke your_private_keyid
+
+For example
+
+ pgp +SECRING=keyringPath/secring.skr -kv
+
+Input the passphrase, then answer 'y' to make the key the ultimately trusted introducer and the default signing key. Answer 'n' to the other questions.
+
+=item *
+
+Sign all the keys on the public key ring with the default signing key by calling the command
+
+ pgp -ks public_keyid 
+
+for each public key. For example
+
+ pgp +PUBRING=keyringPath/pubring.pkr -ks 0x12345678 
+
+=back
+
+Finally, once the key rings have been created and all the keys on them signed they maybe moved to a directory of the users choice (although the file names must be F<pubring.pkr> and F<secring.skr>) The C<pgp_config_path> keyword value in F<reltools.ini> should then be modified to this path. 
+
+=head2 Configuring GnuPG
+
+The tools have been tested with versions 1.06 and 1.4.7 of GnuPG and assume that the C<gpg.exe> executable exists somewhere in the users path.  You can either generate a new key pair or you can import PGP keys.
+
+=head3 Generating a New Key Pair
+
+To generate a new GPG key pair use the command
+
+ gpg --gen-key
+
+and follow the on screen instructions.
+
+=head3 Using existing PGP Keys
+
+GnuPG can use key rings created by Network Associates PGP (see above) just rename the files to F<pubring.gpg> and F<secring.gpg>. If the user wishes to create GnuPG key rings then follow the steps below
+
+=over 4
+
+=item *
+
+Export the keys from a PGP keyring using the method described in the section above
+
+=item *
+
+Import the keys onto the public and private key rings using the command:
+
+ gpg --import keyfile
+
+For GnuPG 1.06 (but not for GnuPG 1.4.7) an additional flag needs to be set to import private keys.  Use the command:
+
+ gpg --allow-secret-keys --import keyfile
+
+If the user wishes to use key rings which are not stored in the default location the '--homedir' option must be used. For example
+
+ gpg --homedir keyringPath --import somePublicKeyFile.asc
+
+As before, if importing private keys using GnuPG 1.06, the '--allow-secret-keys' flag is also needed (this flag is not necessary if using GnuPG 1.4.7).  Use the command:
+
+ gpg --homedir keyringPath --allow-secret-keys --import someSecretKeyFile.asc
+
+=item *
+
+Check that the keys exist on the key rings using
+
+ gpg --homedir keyringPath --list-keys
+ gpg --homedir keyringPath --list-secret-keys
+
+=back
+
+Once the key rings have been created they maybe moved to any directory (keeping the file names as F<pubring.gpg> and F<secring.gpg>). The C<pgp_config_path> keyword value in F<reltools.ini> should then be modified to this path.
+
+=head2 PGP vs GPG compatibility
+
+When exporting or importing with GPG defined as your 'pgp_tool' , and when using keys provided by PGP which employ a patented algorithm such as IDEA, an appropriate plugin will have to be installed for use by GPG.
+
+=head1 Exporting releases
+
+To export a single release to the remote site use the C<exportrel> command. For example 
+
+ exportrel mycomp myver -v
+
+to export a complete environment use the C<exportenv> command. For example
+
+ exportenv mycomp myver -v
+
+C<exportenv> will attempt to export every release in the environment of mycomp myver.
+
+Both commands will only attempt to export a release if it is listed in the export table and does not already exist in the remote archive.
+Using the C<-f> option will force releases to be exported even if they already exist on the remote site (again this only applies to components existing in the users export table)
+
+If the C<-r> option is used and the FTP connection is dropped during the upload of a release, the tools will automatically reconnect to the FTP site and resume the upload. This feature may not be supported by some FTP servers.  
+
+=head1 Importing releases
+
+To import a single release to the remote site use the C<importrel> command. For example 
+
+ importrel mycomp myver -v
+
+to import a complete environment use the C<importenv> command. For example
+
+ importenv mycomp myver -v
+
+C<importenv> will attempt to import every release in the environment of mycomp myver. If mycomp myver does not exist in the local archive it will import it, read its environment information and then import the rest of the environment.
+
+C<importrel> has a C<-f> option which will force the import of a release even if it already 
+exists in the local archive
+
+If the C<-r> option is used and the FTP connection is dropped during the download of a release, the tools will automatically reconnect to the FTP site and resume the download. This feature may not be supported by some FTP servers.  
+
+=head1 COPYRIGHT
+
+ Copyright (c) 2000-2009 Nokia Corporation and/or its subsidiary(-ies).
+ All rights reserved.
+ This component and the accompanying materials are made available
+ under the terms of the License "Eclipse Public License v1.0"
+ which accompanies this distribution, and is available
+ at the URL "http://www.eclipse.org/legal/epl-v10.html".
+ 
+ Initial Contributors:
+ Nokia Corporation - initial contribution.
+ 
+ Contributors:
+ 
+ Description:
+ 
+
+=cut