UForge Platform Overview¶

UForge is a scalable multi-tenant platform. UForge can be split into the following distinct parts.

• UForge Server – This contains all the business logic of UForge, handling all incoming user requests.
• Meta-data SQL Store – A database holding all the configuration information and data of the platform.
• LDAP Service – LDAP holding user authentication and access information
• IDM Service – Authentication and authorization module
• Generation Cluster – A grid engine for scheduling and executing image generations
• Proxy cache - Squid

The UForge platform can be deployed on physical machines or in a virtualized or cloud environment.

UForge Server. The UForge Server is a RESTful (Representational State Transfer) web service built on top of Java and using the JSR-311 reference implementation (project Jersey). UForge Server is based on the design principles of REST and Resource Orientated Architecture (ROA). Resources are references with a unique global identifier (URI). UForge Server uses the semantics of the HTTP protocol to manipulate these resources. The HTTP response codes are used to determine whether a user’s request was treated successfully or not.

Information is returned to the client in either XML or JSON, depending on the “Accept-Type” header attribute used by the client. If no “Accept-Type” header is provided, XML is returned by default. To ensure security, communication with the UForge Server is done via HTTPS. UForge Server provides authentication (AuthN) and authorization (AuthZ) modules. These modules can be customized by the customer to provide or use an alternative mechanism for authentication and authorization. By default these modules communicate with the IDM service. This service determines whether a request has the correct authentication and the correct access.

The UForge Server interacts with the SQL Store using Hibernate. Hibernate is a high-performance Object/Relational persistence and query service. Hibernate maps from Java classes to database tables and from Java data types to SQL data types. It provides data query and retrieval facilities, providing a buffer between the two data representations and enables a more elegant use of object orientation on the Java side. The UForge Server is deployed inside a web/application server container. UForge, by default, uses Glassfish (v3) as the application server container.

Proxy Cache. UForge AppCenter includes a proxy cache. The proxy used is Squid. It is used for caching and centralizes all outgoing traffic. This improves the performance of UForge, specifically for the population of distribution repositories.

IDM Service. The UForge Identity management module is based on Apache Syncope (APL2 licence). The module allows management of auditing (reports), policies, roles, users, tasks and entitlements. At present UForge uses this module for authentication and role-based access control (authorization). The persistence store for the UForge IDM is the SQL Store (described below) and there is a resource connector to the LDAP Service for storage of roles/users and entitlements in an ldap repository backend. The IDM service is deployed inside a web/application server container. UForge, by default, uses Glassfish (v3) as the application server container.

This IDM Service can be extended to provide a wider identity and access management (IAM) integration to an existing enterprise or corporate IAM system or to a brand new standards compliant IAM system(s) by using open source industry standard resource connectors.

LDAP. This service is an industry standard powerful AuthN ldap (v3) pure java server, based on the open source ForgeRock’s OpenDJ offering. This can be run in single instance mode or multi-master replication mode for robustness.

SQL Store. This is a relational database holding all the meta-data of UForge. Meta-data includes such items as:

• Appliance information including which operating system packages are included, install profile, middleware and configuration information.
• Images that have been generated from an appliance
• Images that have been published to a virtual or cloud platform
• Package information for an operating system
• Third party project software components

By default MySQL is used as the SQL Store.

Generation Cluster. Image generation is I/O intensive and may take several minutes to complete. Consequently an HPC cluster is used to execute image generation jobs. There are two parts to this cluster:

• One or more compute nodes to execute a generation job
• A resource management system or batch scheduler that manages the reservation and access to the compute nodes

The resource management system holds its configuration information inside the meta-data SQL Store. The generation cluster is based on an open source project called OAR that is heavily used in production clusters of over 5000 nodes capable of handling over 5 million jobs.

UForge Clients. UForge provides a client, called UForge Portal that connects to UForge Server via HTTPS. This provides an interactive, visual experience when designing appliances or application stacks that can be deployed on physical, virtual and cloud environments. Consequently, UForge does not need to provide any presentation information to the client, greatly reducing the information (and therefore bandwidth) sent to the client.

UForge allows users to implement their own clients to interact with UForge. UForge provides a RESTful API, allowing businesses to create a mashup and expose certain functionalities of UForge in their websites and portals. UForge provides two SDKs:

• Java
• Python

Users can use other languages to communicate with UForge.

Repository Caching¶

UForge AppCenter uses a repository cache in which it stores OS repositories as new images are generated. This means that the cache is empty when the AppCenter is installed and will be populated as images are generated by users. The cache ensures that all the versions a user needs are always available to generate images. As users generate images, the AppCenter connects to the official repositories to get the repositories and stores them in the cache.

Reliability¶

Fault tolerance is an important consideration for large-scale deployments. UForge platform has several types of data that must be replicated.

• The meta-data stored in the SQL store. The meta-data SQL store is replicated by using either master-slave or clustering. Both these configurations are supported by Percona Server. These configurations help scale-out the system and provide a level of fault tolerance if one of the database servers fail.
• The LDAP service data can be replicated over multiple LDAP instances via MMR (Multi-Master Replication)
• Binary data including operating system packages, project packages, uploaded software packages, license files, generated images and logo images. The binary data is stored on a storage system. This can be on a local filesystem of the database or on a NAS or SAN. This data is transparently replicated using RAID techniques.

In order to make the web service tier fault tolerant, multiple web servers can be deployed and load balanced. The administrator may also wish to have multiple load balancers in case the load balancer itself fails.

Security¶

UForge communicates with clients using HTTPS to ensure a secure connection. However, when deploying UForge, other security measures should be considered:

• Add a firewall in front of the web service tier, to only expose the HTTPS port.
• Provide a logical sub-network to protect the database, LDAP, storage and generation cluster (DMZ).

Storage Considerations¶

The UForge platform requires a significant amount of storage. During the configuration it is important to size the local storage, the various node instances of the deployment and, if any, the size of the shared remote storage. You will need both a local and a remote file storage.

Local storage is used for installing the UForge service software and free disk space for log files.

The SQL Store uses the local storage to store all the database meta-data. Finally a compute node used to generate an image requires local free disk space to generate one or more images from an appliance template.

A remote storage system (NAS or SAN) is used to store:

• Operating system repositories (this will be empty at the beginning and will grow as images are generated)
• Project catalog package binaries
• Binaries uploaded by users using UForge
• Generated images (copied from a compute node once the generation is complete)

For small deployments, the remote storage system can be on a local filesystem of the generation cluster.

Operating System Cache Repositories and Projects. The OS repositories are no longer stored in the UForge AppCenter. UForge AppCenter uses cache repositories in order to generate appliance templates. Therefore its size will grow and is completely variable. What consumes space are the images generated and the binaries uploaded in MySoftware. You can limit the space used by setting user quotas.

The size of projects also vary, however are usually in the 10 to 100 MB range. Consequently they take up a very small percentage of the entire disk space.

Image Generation. Compute nodes require local storage to create the disk images during the generation phase of an appliance template. To calculate the local storage required by a compute node, the generation of an image needs to be understood. There are six phases to the generation of an image:

• Phase 1: Check if the packages are in the cache. If they are not, download them and save to cache.
• Phase 2: Create a virtual disk for package installation.
• Phase 3: Install the packages, binaries and files to the disk (at this stage the local copy of the packages are deleted to save space).
• Phase 4: Convert the disk to the required target format.
• Phase 5: Compress the created disk.
• Phase 6: Copy the image to a more permanent storage (the remote storage so that the image can be downloaded or published by the user). At this stage the created disk is deleted.

At any given time during the construction of an image, the compute node requires three times as much space as the final image being generated. Since a compute node can generate more than one image simultaneously, the local disk storage for a compute node can be calculated as follows:

average image size x simultaneous generations x 3

Image sizes vary from 300 MB to 12 GB. Note this is the disk size required to install all binary packages. A UForge compute node uses ‘sparse’ filesystem so that ‘free’ disk space required by a virtual machine does not need to be allocated during the generation of that virtual machine.

For a compute node configured to generate 10 images simultaneously and assuming that an average image size is 8 GB, the minimum local storage required by a compute node is:

8 x 10 x 3 = 240 GB

User Disk Space. Each user on UForge can generate images and also upload their own software. The user software is stored on the remote storage. Once an image has been generated it is also stored on remote storage allowing the user to download or publish the image directly to a virtual or cloud platform at a later stage. User uploaded software is usually a small percentage of the disk space compared to generated images. Note, that as the user has the appliance template, an image can be regenerated at any time, therefore, images can be deleted to save disk space. The total disk space required to store uploaded software and user images can be calculated as follows:

user disk quota x total number of users

For example, a UForge platform providing all the operating systems UForge supports for 100 users, each having a quota of 18 GB (equivalent to having a maximum of 15 stored images of 1GB each and 3GB of uploaded software), the remote storage required is: 1880 GB (1.88 TB).

Depending on the replication policy used for the remote storage, the total remote storage may have to be larger. Note that it may not be necessary to replicate all the information stored in the remote storage. Only important information must be replicated, including:

• the uploaded user software
• operating system repositories (this may be optional if there are backups of the operating systems elsewhere.)

Images generated are usually not replicated, as the image can be regenerated from the appliance template stored in the SQL Store.

Scalability through Partitioning¶

UForge was designed from the ground up to scale to meet the needs of businesses and service providers with 100,000s of users. The key to scaling is partitioning. Effective partitioning is based on leveraging “locality of reference” for both processing and data – if certain servers are specialized to solve a subset of the bigger problem, then the essential code and date are more likely to be in memory or close at hand. Partitioning techniques include vertical partitioning of functional tasks and horizontal partitioning of data and associated processing. Partitioning also helps to implement security to the platform.

Partitioning is increased by other distributed system techniques like automated replication, load balancing and failover.

Vertical Partitioning allows complex processing tasks to be divided into subtasks that can be independently optimized and managed. Vertical partitioning in UForge primarily consists of off-loading or splitting the I/O intensive generation tier, web service tier and database tier.

This allows the administrator to scale-up independently the number of CPUs, RAM and disk size for each of the tiers.

Horizontal Partitioning is crucial for large scale deployments. UForge is horizontally partitioned for larger deployments where thousands of users are required to interact simultaneously with the system.

One of the big bottlenecks, however, in such architectures is the database. When scaling out the web service tier, the number database reads and writes increases, and therefore the database becomes saturated.

Firstly UForge uses Db sharding. This basically consists of splitting up the data into buckets (shards) that can be stored on more than one database instance. The second is caching (memcached) which is an in-memory key-value store for small chunks of arbitrary data from results of database calls. This reduces the amount of potential reads directly into the database.

To help scale out further you can also set up a database cluster, providing multiple database instances to the web service tier (the default database service does not support clustering).

Such bottlenecks can also be reduced by scaling-up (vertical partitioning) where more RAM and CPU is provided to the machine.

The generation cluster is intrinsically scalable, allowing the administrator to easily add new compute nodes to scale-out the number of simultaneous generations. OAR also provides the ability to deploy multiple schedulers and to configure them in master-slave mode.

Image Generations¶

Image generations are very I/O intensive compared to CPU, consequently only 1 core per simultaneous generation is required. Therefore for 10 simultaneous generations, a total of 10 cores are required for the compute notes.

The generation capacity of UForge depends on the total number of subscribers using the service. From experience, the ratio between generation capacity per week and the number of subscribers can be calculated as:

number of subscribers x 0.022 = generation capacity/week

This is assuming that UForge is used 24 hours a day. If the service is only used in one geography, then users will typically use the platform within an 8 hour period. Therefore the generation capacity will have to be multiplied by 3 (as the other 2/3 of the day, no generations will take place). For an 8 hour day, the generation capacity per week required for a certain number of subscribers can be calculated as:

number of subscribers x 0.066 = number of generations/week

On average, a generation takes about 5 minutes (this depends upon the size of the image being created and whether it requires to be compressed). For each core used to generate images, the total generation capacity per week can be calculated as:

12 x number of hours x 7 = generation capacity per core

For an 8 hour period:

12 x 8 x 7 = 672/week (per core)

For an 24 hour period:

12 x 24 x 7 = 2016/week (per core)

Estimating Scan Size¶

It is difficult to estimate sizing of scans. However, the following guidelines may be useful to plan your first scan:

average scan size x number of scans

Scan sizes vary from 100 KB to 12 GB

You should note that the data that will be scanned does not include operating systems known by UForge. For example, Debian or other OS data will not be included in the scan size.

Also, if you have already run a scan, only the delta information will be included.

Deployment Example¶

How to organize your UForge configuration depends on the specific customer needs. This may include:

• The number of users as well as the number of simultaneous connections to the platform
• The number of simultaneous generations
• The number of operating systems offered by UForge
• The number of projects in the project catalog
• The SLA of UForge
• Whether the service needs to be reached over multiple sites
• Whether UForge is exposed to 3rd party customers and partners, or for internal use only

Note that UForge can be deployed on physical machines or on a virtual or cloud platform. The word ‘node’ describes either the specification of a physical machine or a virtual machine instance running in the virtual or cloud environment.

Network Topology¶

In order to optimize scalability, you should use a dedicated network subnet for UForge service.

If you want to deploy a public UForge service, you can use a public IP address for each component:

UShareSoft recommends using a firewall with the NAT technology to map a public IP address to a private IP address. This allows you to use public IP addresses only for the Web Front-end and the Web Service. The other services stay hidden from the rest of the world.

For a private network, you can use a NAT translation, but it is better to use the firewall in gateway mode and filter the traffic. This way you can open ports on the different services.

Minimum Software Topology¶

For the minimum software topology, use all services without security or fault tolerance.

For each of these components we recommend the following minimal (hardware or virtual) specification:

Security Options¶

To increase the security of the UForge service, you can add replication in master/slave of the database component and the LDAP component.

The minimal requirement is 1 slave for the database and 1 slave for the LDAP service. Of course, you can add more slaves for each of these services.

See the specification of these options:

High Availability¶

High Availability can be attained with the redundancy of all services. However, the database and the LDAP service have not yet been tested with the clustering mode.

For the moment UShareSoft recommends using the “security options” for these services. This is a point of failure.

All other services can be clustered. For clustering a service you will need a pool of load balancers (physical or virtual).

All other services keep the same configuration, as seen above.

UForge Installation Overview¶

To install a fully functioning UForge AppCenter, you must install and configure the UForge services as well as populate the UForge Repository with the operating systems you wish to build your server templates from. To make the UForge installation process as easy as possible, UShareSoft provides an external hard drive UForge Setup Disk that contains:

• UForge Operating System Repository – all the packages and updates for each open source operating system distribution supported by UForge. For other operating systems including RedHat Enterprise Linux, you must have access rights to the operating system repositories
• Default Projects Catalog – all the 3rd party software that UShareSoft has packaged for its own Online platform Project Catalog
• UForge AppCenter Installation Images – ISO image or VM images to install the UForge services

UForge Repository Setup¶

The UForge Repository is a storage area containing:

• Operating system packages and updates
• Project catalog binaries
• User My Software binaries
• Generated images from users using the platform

The operating system and project binaries are separated from the My Software binaries and the images generated.

The UForge Setup Disk contains all the operating system and default project binaries information that needs to be copied to the UForge Repository. This repository can be shared storage or in the case where the entire UForge platform is being installed on one machine, can be on the local disk.

If you want to have the UForge Repository setup on a local disk, you must first install UForge prior to setting up UForge Repository. Otherwise, if this is shared storage, the UForge Repository can be setup independently.

The UForge Repository must be setup properly prior to completing the final configuration step. You must first populate the UForge database with the operating system package meta-data before you run the configuration phase described in Configuring UForge.

You can set up the UForge Repository either:

• on a shared storage
• on a local storage

UForge Repository on Shared Storage¶

When using shared storage NFS is used to share the information between the various UForge nodes. To setup the NAS or SAN for the UForge Repository you must create two shared directories, one for the operating system data and the other for all the user data (My Software and images generated).

To setup the shared storage:

1. Log in to the machine where the NFS server is running

2. Create the operating system directory, for example: /volume1/DISTROS

   The following NFS options are required:

   *(rw,async,no_wdelay,no_root_squash,insecure_locks,anonuid=0,anongid=0)
   

3. Create the user data directory, for example: /volume1/USER_DATA

   The following NFS options are required:

   *(rw,async,no_wdelay,no_root_squash,insecure_locks,anonuid=0,anongid=0)
   

4. Check the mount points:

   mount 192.20.777.205:/appstore_qualif_data/ /mnt
   su - glassfish
   cd /mnt
   

5. Execute the command:

   touch test
   

6. If it returns:

   touch: cannot touch `test': Permission denied
   
   Then execute the following commands (as root)
   
   .. code-block:: shell
   
           cd /mnt
           chown -R glassfish:glassfish .
   

7. Confirm you can create a file on /mnt as user glassfish. Then perform the following:

   cd ~
   umount /mnt
   

8. Once these directories have been exported, use the UForge Setup Disk to copy all the operating system information to the DISTROS sub-directory. To mount the shared directory on the machine where the UForge Setup Disk is plugged to:

   mount <nfs server ip address>:/volume1/DISTROS /mnt
   

Then copy the DISTROS information from the Setup Disk to the shared directory:

rsync -a –-progress <my disk>/DISTROS/ /mnt/DISTROS/

UForge Repository on Local Storage¶

When using local storage, UForge must already be installed, but not configured. Create two directories one for the operating system data and the other for all the user data (for example My Software and images generated).

1. Create the operating system directory, for example: /space/DISTROS

2. Create the user data directory, for example: /space/USER_DATA

3. Now copy all the operating system information from the UForge Setup Disk to the DISTROS sub-directory:

   //# rsync -a –-progress /<disk directory>/DISTROS/ /space/DISTROS/
   

Installing from an ISO¶

To install UForge from the ISO image:

1. Attach the ISO to a VM or burn the ISO to a DVD (for installing to a physical machine, note the machine will require to have a DVD disk drive).
2. Boot the system from the ISO.
3. Choose the default menu proposed by the installer.
4. Choose the keyboard layout you want to use.
5. Set the timezone.
6. Set the root linux password.
7. Wait for the install to finish, then reboot the system and detach the ISO from the VM or remove the DVD from the disk drive.
8. Once the system reboots, accepts the EULA license agreement.

For a multi-node installation, repeat these steps for every physical or VM instance you wish to install.

The installation phase is complete, you are now ready to configure the UForge platform, see Configuring UForge.

Installing from a VM Template¶

A number of virtual machines have already been prepared by UShareSoft to make it easier to install quickly UForge on a virtualized or cloud environment. If your environment does not support the proposed VM formats, then install UForge using the ISO image, as described in Installing from an ISO.

To install UForge from a VM template.

1. Import the VM to the cloud datastore or public template library.
2. Use the cloud or virtualization management platform to instantiate one or more instances of the VM template.
3. Recuperate the console of the newly created VM instance.
4. Accept the licensing agreement.
5. Choose the keyboard layout you want to use.
6. Choose the UNIX root user and guest user passwords.
7. Set the time zone of the VM.
8. Choose Accept All and Continue.

The installation phase is complete, you are now ready to configure the UForge platform, see Configuring UForge.

Configuring UForge¶

Once the installation is complete on all the nodes you wish to use for the UForge platform, you are now ready to configure all the UForge platform services. This is done via the UForge Deployment Wizard that helps guide you through the final steps of the installation process.

To launch the UForge Deployment Wizard, use your browser and go to one of the nodes that have been installed:

http://<ip address of the node>:9998/deployments

Fill in the wizard, note that all the fields are mandatory.

1. Enter the Organization name. This is the name of the default Organization. The organization groups all the operating systems, formats and users for the platform.

2. Enter an email address. This is the email address of the root administrator of UForge. All administration email notifications are sent to this email address.

3. Set the root administrator’s password. The password must be at least five characters long, including alphanumeric characters and the following special characters !#$%&’()*+,-/:;<=>?@[]/^_{|}~`. Spaces are not allowed at the beginning or end.

4. Provide a username, email and password for an initial user account to be created. This user account will have administration access rights for the default Organization.

5. Provide the UForge activation key and credential information to be able to receive UForge updates. If you do not have this information, please contact UShareSoft.

6. Select the operating systems and formats you would like to install. When you select an OS, a default mirror location is indicated. This is used for synchronization of packages and distributions. You can either accept the default values or modify the value to synchronize with another mirror.

7. Decide whether you would like to populate UForge with UShareSoft’s default project list. This list must already be copied to the UForge repository in the storage used for this deployment.

8. Set the internet connection. By default, UForge expects to have a direct connection to the internet. If you de-select this option, you will need to enter the proxy hostname and port.

9. Set the SMTP Server to use for sending email notification messages created by UForge. If you want to use a SMTP relay, then also indicate the relay hostname and port number.

10. Click next to continue.

11. Enter the Web Server IP address, external hostname and the database IP address.

12. Select if OS and image storage should be local or remote. OS storage will be used for distributions, which image storage will include user data such as images, projects, mysoftware and other user data created with UForge Portal.

    If you choose to use a remote storage, indicate the NFS server with mount point and you should enter the full path for the OS directory e.g. /DISTROS.

    If you select remote storage for the image store, you have to make sure that the path USER_DATA exists, with the correct permissions i.e. glassfish:glassfish (see :ref: repository-shared-storage, step 4, Check mount points, for more detail).

13. Indicate the generation cluster compute node hostnames. You can add additional compute nodes by clicking the add button.

14. Once you have finished the configuration, click the Deploy button.

    Note

    The deployment may take a few hours, depending on the number of operating systems you have chosen.

15. Once the deployment is complete, click Finish.

# cd /var/log/UShareSoft
# /bin/rm -rf oas-deploy

Testing the Deployment¶

Once the configuration phase is complete, you may wish to carry out some basic sanity tests to ensure that the UForge platform is running normally:

Step 1: Check if the web service is operational

Use the values in the uforge.conf to contact the web service and expect a 200 OK response.

Get the values form the uforge.conf and add them to some environment variables (you could also just manually view the uforge.conf)

eval `grep '^UFORGE_WEBSVC_\|^UFORGE_GF_INTERNAL_IP\|^UFORGE_GF_HTTP_PORT\|^UFORGE_GF_WEBSVC_ROOT_CONTEXT' /etc/UShareSoft/uforge/uforge.conf`

Run a simple http request (using basic authentication) using curl

# curl http://$UFORGE_GF_INTERNAL_IP:$UFORGE_GF_HTTP_PORT/$UFORGE_GF_WEBSVC_ROOT_CONTEXT/users/$UFORGE_WEBSVC_LOGIN -H "Authorization:Basic $UFORGE_WEBSVC_LOGIN:$UFORGE_WEBSVC_PASSWORD"
--verbose

* About to connect() to 10.0.0.240 port 9090 (#0)
*   Trying 10.0.0.240... connected
* Connected to 10.0.0.240 (10.0.0.240) port 9090 (#0)
> GET /ufws-3.0/users/root HTTP/1.1
> User-Agent: curl/7.20.1 (x86_64-redhat-linux-gnu) libcurl/7.20.1 NSS/3.12.8.0 zlib/1.2.3 libidn/1.16 libssh2/1.2.4
> Host: 10.0.0.240:9090
> Accept: */*
> Authorization:Basic root:welcome
>
< HTTP/1.1 200 OK
< X-Powered-By: Servlet/3.0 JSP/2.2 (GlassFish Server Open Source Edition 3.1.1 Java/Sun Microsystems Inc./1.6)
< Server: GlassFish Server Open Source Edition 3.1.1
< Last-Modified: Thu, 03 May 2012 08:32:18 GMT
< ETag: "ef286bf07b8d18928287e12cb122ccf2"
< Content-Type: application/xml
< Content-Length: 5477
< Date: Thu, 03 May 2012 08:33:11 GMT
...<rest of the body removed>

Step 2: Check to see if the Database is running

The database service should be running and available on the port 3306 and that the database table is present. The Percona Server instance should have “usharedb” and “oar”

# service mysql status
MySQL running (22661)                                      [  OK  ]

Get the values form the uforge.conf and add them to some environment variables (you could also just manually view the uforge.conf)

# eval `grep '^UFORGE_DB' /etc/UShareSoft/uforge/uforge.conf`
# echo "show databases" | mysql -f -N -u $UFORGE_DB_LOGIN -p$UFORGE_DB_PASSWORD -h db
information_schema
mysql
oar
performance_schema
usharedb

Step 3: Check the generation cluster resources

Check that all the cluster resources are available (‘alive’). On each compute node

# oarnodes | awk '/resource_id/ {n=$NF} /state : Suspected/ {printf "oarnodesetting -s Alive -r %s\n",n}' | sh

This should return without any output.

Adding a Compute Node¶

You can add a new OAR compute node which was instantiated from UForge but which was not configured as part of the initial deployment as follows.

1. Make a snapshot of the UForge Server (to be able to come back to the state without the additional OAR compute node).

2. Initial setup: oar-server and oarnode1 to oarnodeN already configured

   Name oarnodeX and IP-oarnodeX respectively the name and IP address of the new node to be added to the UForge “cluster”.

3. Copy over /etc/hosts from oarnode1 to oarnodeX with mods
4. Get first local network interface (eth0)

ITF=`cat /proc/net/dev | grep : | cut -d ':' -f 1|grep -v lo | tr -d ' '| head -1`

5. Get IP address associated with this interface

IP=`/sbin/ip -o addr show $ITF 2>/dev/null| grep 'inet ' | awk '{print \$4}' |
sed -e 's?/.*??'`

6. Modify and copy /etc/hosts

sed -e 's/\<oarnode1\>/oarnodeX/g' /etc/hosts | awk -v ip=$IP -v name=oarnode1
'{print}END{printf "%s %s\n",ip,name}' | ssh IP-oarnodeX dd of=/etc/hosts

7. Copy over uforge.conf file and others

rsync -a /etc/UShareSoft/uforge/uforge.conf IP-oarnodeX:/etc/UShareSoft/uforge/
rsync /etc/oar/oar.conf IP-oarnodeX:/etc/oar/
rsync /etc/ssh/sshd_config IP-oarnodeX:/etc/ssh
rsync -a ~oar/.ssh IP-oarnodeX:~oar

8. Run the following commands on all oarnode1 .. oarnodeN and oar-server but not oarnodeX. This adds new node in all machines /etc/hosts

awk 'BEGIN{d=1}/\<oarnodeX\>/ {d=0}{print}END{if(d==1){print "IP-oarnodeX
oarnodeX"}}' /etc/hosts > /tmp/hosts.NEW
diff -q /tmp/hosts.NEW /etc/hosts >/dev/null
if [ $? -ne 0 ]; then
rsync -a /etc/hosts /etc/hosts.SVG-`date +"%Y-%m-%d"`
cp /tmp/hosts.NEW /etc/hosts
rm -f /tmp/hosts.NEW
fi

9. Run the following commands on oarnodeX

chmod 666 /etc/oar/oar.conf
/opt/UShareSoft/uforge/conf/oar_user_setup.sh
cp /opt/UShareSoft/uforge/tmpl/nfs.tmpl /etc/sysconfig/nfs
cp /opt/UShareSoft/uforge/tmpl/mountisos_init /etc/init.d/mountisos; chkconfig
--add mountisos
for s in ntpd glassfish tomcat mysql httpd oar-server openstack-glance-api
openstack-glance-registry oas oas-deploy; do service $s stop; chkconfig --levels
0123456 $s off ; done >/dev/null 2>&1
ntpdate pool.ntp.org ; service ntpd start
for s in oar-node ntpd postfix mountisos; do chkconfig --levels 2345 $s on; done
service ntpd stop ; ntpdate pool.ntp.org ; chkconfig ntpd on ; service ntpd
start
service mountisos start
service oar-node start
service sshd restart
/opt/UShareSoft/uforge/tools/update_scripts/uforge_update.sh -f >/dev/null 2>&1

10. Run the following commands on oar-server to create new resources on oarnodeX from existing oarnode1 resources

/usr/bin/oarnodes | /bin/awk '/network_address=oarnode1/
{s=$0;gsub(".*nature=","",s);gsub(",.*","",s);printf "/usr/sbin/oarnodesetting
-a -h oarnode3 -p cpuset=0,nature=%s\n",s}' | sh

Removing a Node¶

In order to remove a node, run the following command on the UForge server:

/usr/bin/oarnodes | /bin/awk "/resource_id/ {n=\$NF} /network_address=$
{REMOVENODE}/ {printf \"/usr/sbin/oarnodesetting -s Dead -r %s ; sleep 2;
/usr/sbin/oarremoveresource %s\n\",n,n}" | sh

Modifying the UForge IP Address¶

To modify the UForge IP address or hostname, do the following.

1. If UForge is installed on a single node, launch a terminal on the UForge machine.

2. Use system-config-network to modify hostname <MY-NEW-HOSTNAME>. It should also allow you to change the host name (that is the fully qualified domain name like ufiab.mycompany.com). This will apply the changes automatically to the directories in /etc/sysconfig

3. Ensure that the changes are applied in the following locations, otherwise make the appropriate changes:

   • /etc/sysconfig subdirectory files like ifcfg-XXX where XXX is your main interface name (like eth0)

   • /etc/sysconfig/network for HOSTNAME and GATEWAY

   • /etc/resolv.conf for your DNS configuration

   • /etc/hosts for all host definitions

   • /etc/fstab for remote NFS mounts

   • /etc/UShareSoft/uforge/uforge.conf for the following entries:

     • UFORGE_PROXY_INFOS
     • UFORGE_EXTERNAL_HOSTNAME
     • UFORGE_IAAS_DOWNLOAD_URL
     • UFORGE_NOREPLY_EMAIL
     • UFORGE_URL

   • /etc/udev/rules.d/70-persistent-net.rules

4. Modify the header, footer, IP information in /var/opt/UShareSoft/uforge-client/gwt/uforge/templates/config.xml (except for <c:uForgeUrl>) with the EXTERNAL_URL variable. For more information on modifying the portal information, refer to Rebranding Your UForge GUI.

5. Launch the following two scripts:

   $ /opt/UShareSoft/uforge/tools/update_scripts/uforge_update.sh
   $ /opt/UShareSoft/uforge-client/bin/uforge_ui_update.sh
   

If you have a load balancer where rules have been entered for accessing the UForge web service make sure the URIs match the following parameter in uforge.conf:

UFORGE_GF_WEBSVC_ROOT_CONTEXT=ufws-3.3

For the UForge CLI you should have:

UFORGE_GF_ADMIN_WEBSVC_ROOT_CONTEXT=ufadmws-3.3

Configure Apache and GlassFish Web Services to use SSL Certificate¶

It is highly recommended that all communication with UForge is done via HTTPS. After the initial installation of UForge, neither the HTTP server (Apache) nor the application server (GlassFish) have yet been configured to use a SSL certificate and allowing HTTPS.

To configure both servers to use an SSL certificate:

1. Log in as root to the machine running the UForge Apache and GlassFish Web Services

2. Copy the SSL certificate files locally to the machine. Note that you should have three to four files, for example:

   • SSLCertificateFile: server.crt.pem
   • SSLCertificateKeyFile: server.key.pem
   • SSLCACertificateFile: CA.crt.pem
   • SSLCertificateChainFile: intermediate.CA.crt.pem (this one is optional)

You need to build a self contained certificate as follows:

cat server.crt.pem CA.crt.pem > server_CA_chain.crt.pem

or:

cat server.crt.pem intermediate.CA.crt.pem CA.crt.pem > server_CA_chain.crt.pem

Note that .pem files contain the following type of data for certificate files:

# cat server.crt.pem
-----BEGIN CERTIFICATE-----
MIIHJTCCBg2gAwIBAgIDB25YMA0GCSqGSIb3DQEBBQUAMIGMMQswCQYDVQQGEwJJ
...
aW9uIEF1dGhvcml0eTADAgECGmRMaWFiaWxpdHkgYW5kIHdhcnJhbnRpZXMgYXJl
V4XfZvZtrRcZ
-----END CERTIFICATE-----

And the following data for the key file:

# cat server.key.pem
-----BEGIN PRIVATE KEY-----
MIIEvwIBADANBgkqhkiG9w0BAQEFAASCBKkwggSlAgEAAoIBAQDaRIAE7wrKbS9T
...
GdIr+qaNjk+eZLVsuPsAvwPlsWI/Cip7Zqygtvviteyen0VZbLpRJgbbjXqh9GwP
G33VnWF89pfm5FNRu3WHIf8Ukw==
-----END PRIVATE KEY-----

If this is not the case, refer to the OpenSSL documentation on how to convert certificate and key files from one format to another.

3. Put the following entries in /etc/httpd/conf.d/ssl.conf:

   SSLCertificateFile /etc/pki/tls/certs/server.crt.pem SSLCertificateKeyFile /etc/pki/tls/private/server.key.pem SSLCertificateChainFile /etc/pki/tls/certs/intermediate.CA.crt.pem SSLCACertificateFile /etc/pki/tls/certs/CA.crt.pem

4. Verify the permissions and ownerships of these files

ll -d /etc/pki/tls/certs/server.crt.pem /etc/pki/tls/private/localhost.key /etc/pki/tls/private/ /etc/pki/tls/certs/
drwxr-xr-x. 2 root root 4096 Sep 25 12:05 /etc/pki/tls/certs/
-rw-------. 1 root root 1188 Sep 25 12:05 /etc/pki/tls/certs/server.crt.pem
drwxr-xr-x. 2 root root 4096 Sep 25 12:05 /etc/pki/tls/private/
-rw-------. 1 root root  887 Sep 25 12:05 /etc/pki/tls/private/server.key.pem

5. (Re)start the httpd server:

   service httpd restart
   

If the server does not start, this may be because of a bad certificate, key or CA certificate file. In this case, check the appropriate logs in /var/log/httpd.

6. Verify the validity of the certificates

# openssl s_client -connect localhost:443
...
Verify return code: 0 (ok)
---
Ctrl-C or Ctrl-D to leave openssl client

If there is a problem with the certificate you might get outputs like

    # openssl s_client -connect localhost:443
    ...
Verify return code: 18 (self signed certificate)
    ---

or

    # openssl s_client -connect localhost:443
    ...
Verify return code: 21 (unable to verify the first certificate)
    ---

7. Go to the glassfish configuration directory:

   cd /usr/glassfish-3.1/glassfish/domains/*/config/
   

8. Save the original keystore with the correct permissions and groups:

   rsync -a keystore.jks keystore.jks.ORIG
   

9. Delete the current certificate:

   /usr/java/latest/bin/keytool -delete -alias s1as -keystore keystore.jks -storepass <admin password>
   

Note that the default admin password for a standard GlassFish installation is changeit. So the default command to run is:

/usr/java/latest/bin/keytool -delete -alias s1as -keystore keystore.jks -storepass changeit

10. Convert your certificate pem files to one pkcs#12 file:

    openssl pkcs12 -export -in <SSLCertificateFile CA chain (pem) path> -inkey <SSLCertificateKeyFile (pem) path> -out keystore.pkcs12 -name s1as -passout pass:<admin password>
    

So in our case:

openssl pkcs12 -export -in server_CA_chain.crt.pem -inkey server.key.pem -out keystore.pkcs12 -name s1as -passout pass:changeit

11. Import the newly generated pkcs12 file:

    /usr/java/latest/bin/keytool -importkeystore -srckeystore keystore.pkcs12 -srcstoretype pkcs12 -srcstorepass <admin password> -deststoretype jks -destkeystore keystore.jks -deststorepass <admin password>
    

Giving:

/usr/java/latest/bin/keytool -importkeystore -srckeystore keystore.pkcs12 -srcstoretype pkcs12 -srcstorepass changeit -deststoretype jks -destkeystore keystore.jks -deststorepass changeit
Entry for alias s1as successfully imported.
Import command completed:  1 entries successfully imported, 0 entries failed or cancelled

12. Restart the application service:

    service glassfish restart
    

13. Verify the certificate:

    openssl s_client -showcerts -connect <ip-of-the-uforge-web-service-machine>:<port>
    

Or you can also use same openssl client command than for the Apache server used in step 6.

To verify that the new certificate is correct and if the GlassFish service is accessible from the outside, go to http://www.digicert.com/help/ and type the public name or IP address of your web service. Note that there is no way to specify another port than HTTPS (443) on this page therefore you might need to add a iptables redirection rule like:

# iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 443 -j REDIRECT--to-port 9191

Configuring SMTP Proxy¶

Once your UForge platform deployment has been done you can configure SMTP proxy as follows. In /etc/UShareSoft/uforge/uforge.conf you can modify:

• UFORGE_RELAY_HOST=
• UFORGE_RELAY_PORT=
• UFORGE_RELAY_USER=
• UFORGE_RELAY_PASSWORD=

These can be empty

Then run:

/opt/UShareSoft/uforge/conf/postfix_configure.sh

Configuring the Web Service¶

Each UForge Web Service instance runs inside a Glassfish application server. The web service has the following basic configuration information that is stored in a central configuration file: uforge.conf. The main configuration attributes for the web service are:

• External hostname used for incoming user connections
• External hostname for downloading images (this uses port 80 allowing all cloud platforms to be able to communicate with UForge for publishing images)
• Internal IP address used to connect with the other UForge services
• HTTP port (default: 9090)
• HTTPS port (default: 443)
• Administration console port (default: 4848)
• Administration console credential information (user and password)
• Root context of the web service (for example ufws-3.3)

When installing UForge via the deployment wizard some of the configuration attributes can be decided by the administrator. The deployment wizard also creates the uforge.conf file with all the configuration information.

To view the uforge.conf file:

1. Log in to the web service node as root:

   ssh root@<ip address of the node>
   

2. Open the uforge.conf file:

   vi /etc/UShareSoft/uforge/uforge.conf
   

For more information on Glassfish, see http://glassfish.java.net

Configuring the Database¶

UForge uses the PerconaDB database to store all the UForge meta-data and user information. The web service communicates with the database using hibernate. When installing UForge using the deployment wizard, one database instance is configured.

The PerconaDB database has the following basic configuration information that is stored in a central configuration file, uforge.conf. The main configuration attributes for the database are:

• Administration credential information (user and password)
• Port number (default: 3306)

When installing UForge via the deployment wizard some of the configuration attributes can be decided by the administrator. The deployment wizard also creates the uforge.conf file with all the configuration information. To view the uforge.conf file:

1. Log in to the web service node as root:

   ssh root@<ip address of the node>
   

2. Open the uforge.conf file:

   vi /etc/UShareSoft/uforge/uforge.conf
   

For more information on PerconaDB, see http://www.percona.com

..note:: By default no mechanism is configured to backup the contents of the UForge database. PerconaDB can be configured as a cluster or in master-slave mode to provide reliability and to have a replicate of the data. Regular backups of the database should also be done.

Configuring the Scheduler¶

The scheduler can be configured to throttle the maximum number of:

• generations allowed in parallel per compute node.
• publishes allowed in parallel per compute node. A publish is when a user wishes to upload and register a generated image to a particular cloud environment.
• shares allowed in parallel per compute node. A share is when a user requests to share a template that they have in their private workspace.
• live system scans allowed in parallel per compute node. This is used for migrating live systems from one environment to another.

By default, after installing UForge using the deployment wizard, UForge will have X compute nodes. The scheduler is configured to allow 1 generation that has been chosen during the deployment on each compute node.

You can re-configure the scheduler to have different scheduling policies for different job types for each compute node. This is done be declaring a resource with a nature in OAR. Each nature corresponds to a specific job type. For example by declaring 4 resources with the nature ID 0 for compute node node1 will configure the scheduler to allow up to 4 parallel generations. The following table shows the mapping between the different job types and the nature ID.

# ssh root@<ip address of the node>
# oarnodes
network_address : compute1.example.com
resource_id : 1
state : Alive
properties : deploy=NO, besteffort=YES, cpuset=0, desktop_computing=NO, nature=0, network_address=iso, type=default, cm_availability=0

network_address : compute1.example.com
resource_id : 4
state : Alive
properties : deploy=NO, besteffort=YES, cpuset=0, desktop_computing=NO, nature=1, network_address=vm, type=default, cm_availability=0

# oarnodesetting -a -h node1 -p cpuset=0,nature=0;
# oarnodes
network_address : node1
resource_id : 92
state : Alive
properties : deploy=NO, besteffort=YES, cpuset=0, desktop_computing=NO, nature=0, network_address=vm, type=default, cm_availability=0

# oarnodesetting -h node1 -r 92 -p nature=1;

# oardel <job_id>

Managing the Watchdog Services¶

UForge has a set of watchdog services that carry out housekeeping tasks on a regular basis. These are:

• Cleanup Tickets: Task to remove generated images that are no longer attached to a parent image ticket in the database. This happens when the user “deletes” the generated image from their account. By default this is run once a day at 04:10AM.
• Update Distribution Packages: Task to regularly search the operating system repositories for any new updates and synchronize metadata into the UForge database. By default this is run every hour.
• Reset OAR Resources: Check the OAR scheduler resources and ensure that their state is “Active”. By default this is run every 5 minutes.

Each of these housekeeping tasks are registered as a cron job in the first database node of the UForge platform to schedule the task to be run periodically. The frequency of these tasks can be changed.

To change the frequency of these housekeeping tasks, you need to update the crontab. Each line of a crontab file represents a job and is composed of a CRON expression, followed by a shell command to execute. The syntax is:

dw month day hr min followed by the command to be executed

Where:

• dw is the day of the week (0 - 6) (0 is Sunday, or use names)
• month is 1 - 12
• day is day of the month (1 - 31)
• hr is the hour (0 - 23)
• min is minutes (0 - 59)

To view these cron jobs, log in to the oar scheduler node as root and view the cron jobs:

# crontab -l
*/5 * * * * /opt/UShareSoft/uforge/cron/reset_oar_resources.sh
10 2 * * * /opt/UShareSoft/uforge/cron/cleanup_tickets.sh
10 3 * * * /opt/UShareSoft/uforge/cron/cleanup_scans.sh
42 * * * * /opt/UShareSoft/uforge/cron/update_repos_pkgs.sh
05 * * * * /opt/UShareSoft/uforge/cron/update_repos_local_cache.sh
1 8 * * * /opt/UShareSoft/uforge/cron/drop_caches.sh

To update the crontab, log in to the oar scheduler node as root and edit the crontab

# crontab -e

Tuning the Services¶

You can set the priority of tasks on the UForge platform in the file uforge_services.conf

You can run COMMAND with an adjusted value for the nice value, which affects process scheduling. This allows you to fine tune the order in which services are treated by the platform and allows you to improve performances.

"profile1": {
  "exec": "/opt/UShareSoft/uforge/tool/demo.sh",
  "ionice": {
  "class": 2,
  "level": 7
},
"jvm": {
  "options": [
    "-Xmx2048m",
    "-Xms768m",
    "-XX:PermSize=256m",
    "-XX:MaxPermSize=1024m"
  ],
  "sys-properties": {
    "jna.library.path": "/opt/UShareSoft/uforge/lib"
  }
},
  "nice": {
    "niceness": 15
  }
}

"my_process": {
  "exec": "/opt/UShareSoft/uforge/tools/demo.bin",
  "include": "low_prio",
  "sudo": true
  },

Email Notification Service¶

The UForge platform provides an email notification service to notify the super-user administrator and users via email for certain types of information.

Email notifications are triggered for the administrator when:

• There is a server template generation failure.
• A new user has been created on the platform (or in the case where this is manual, a request for a new user account to be created).
• A user has reported an abusive comment in the Marketplace (App Store) that requires moderation.

Email notifications are triggered to the end users when:

• A new user account has been created using their email address. This includes information on their credential information to access UForge.
• For all the templates the user is “watching” in the Marketplace (App Store), emails are sent when the template is updated or a new comment has been added to the template.

Customizing UForge Authentication for SSO¶

You need to build a custom AuthN/AuthZ module in order to perform Single Sign On to the UForge Platform.

The goal is to gain authenticated and authorized access to the RESTful UForge Webservice underlying methods. These methods are protected by a SecurityFilter and a SecurityContext using what is called a filter chain. The UForge Platform uses JSR 311(JAX-RS: The JavaTM API for RESTful Web Services), JSR 250 (Common Annotations for the JavaTM Platform) and Jersey (RESTful Web Services in Java).

To gain access through this filter chain to the UForge Webservice methods, you first need to be “Authenticated” (to prove who you are) and then be “Authorized”, that is, be granted entitlements to perform or access certain methods of the UForge Webservice.

So, in order to connect to the UForge Webservice you first have to pass through the “authentication filter chain” of the web service. These filters are defined by default in web.xml

By default there are two filters:

• BasicAuthenticationFilter: the Basic method from RFC2617
• APIKeyAuthenticationFilter: the UForge internal APIKey authentication.

You should create an implementation of the interface IAuthenticationFilter returning an object implementing IUserAuthentication if authentication is ok, an exception if the authentication is invalid and null if your filter can not handle the request authentication.

The following is a basic example of an implementation of the RFC.

package com.usharesoft.authentication;
import com.sun.jersey.api.core.HttpRequestContext;
import com.sun.jersey.core.util.Base64;
import com.sun.jersey.spi.container.ContainerRequest;
import com.usharesoft.common.messages.User;
import com.usharesoft.db.DbAccess;
import com.usharesoft.db.DBException;
import com.usharesoft.services.IDMService;
import com.usharesoft.services.ServicesContext;
import com.usharesoft.services.exceptions.UForgeException;
import org.apache.log4j.Logger;
import org.hibernate.Criteria;
import org.hibernate.criterion.Restrictions;
import java.net.URI;
import java.util.List;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

public class BasicAuthenticationFilter implements IAuthenticationFilter {
    private static final Logger logger = Logger.getLogger(BasicAuthenticationFilter.class);
    private static final Pattern CREDENTIALS = Pattern.compile("^basic\\s+(?.*)$", Pattern.CASE_INSENSITIVE);
    private static final Pattern USER_PASS = Pattern.compile("^(?[^:]*):(?.*)$", Pattern.CASE_INSENSITIVE);
    @Override
    public IUserAuthentication filter(ContainerRequest containerRequest) throws UForgeException {
        logger.trace("Getting Auth from Http Header");
        return getUserAuthentication(containerRequest);
    }
    protected IUserAuthentication getUserAuthentication(HttpRequestContext containerRequest) throws UForgeException {
        /*
        * Get the authentication information from the HTTP header Return an
        * empty string if no authorization information is found
        */
        List authorizationList = containerRequest.getRequestHeaders().get("Authorization");
        if (authorizationList == null || authorizationList.isEmpty()) {
            return null;
        }
        /*
        * Get the first value as there should only be one value here as we will
        * only support Basic authentication for the moment Remove the Basic Tag
        */
        String credentials = authorizationList.get(0);
        logger.trace("Credentials: " + credentials);
        /*
        * Decode credentials
        */
        Matcher matcher = CREDENTIALS.matcher(credentials);
        if (!matcher.matches()) {
            logger.debug("Not matched Authorization header: " + credentials);
            return null;
        }
        /*
        * Consider that we match
        */
        /*
        * Decode base64 credentials
        */
        String base64basicCredentials = matcher.group("credential");
        if (!Base64.isBase64(base64basicCredentials)) {
            logger.warn("Invalid Base64 basic-credentials: " + base64basicCredentials);
            throw new UForgeException(UForgeException.UNAUTHORIZED, "ERROR.AUTHENTICATION.INVALID");
        }
        String basicCredentials = Base64.base64Decode(base64basicCredentials);
        /*
        * Decode user-pass
        */
        matcher = USER_PASS.matcher(basicCredentials);
        if (!matcher.matches()) {
            logger.warn("Invalid basic-credentials: " + basicCredentials);
            throw new UForgeException(UForgeException.UNAUTHORIZED, "ERROR.AUTHENTICATION.INVALID");
        }
        /*
        * Compute fields
        */
        String userId = matcher.group("userId");
        String userName;
        String targetUserName = null;
        if (UserAuthentication.isCompositeUserTargetUser(userId)) {
            userName = UserAuthentication.getCompositeUser(userId);
            targetUserName = UserAuthentication.getCompositeTargetUser(userId);
        } else {
            userName = userId;
        }
        String password = matcher.group("password");
        /*
        * Sanity checks
        */
        if (password == null) {
            logger.warn("Invalid password");
            throw new UForgeException(UForgeException.UNAUTHORIZED, "ERROR.AUTHENTICATION.INVALID");
        }
        if (userName == null) {
            logger.warn("Invalid user");
            throw new UForgeException(UForgeException.UNAUTHORIZED, "ERROR.AUTHENTICATION.INVALID");
        }
        return getUserAuthentication(containerRequest.getRequestUri(), userName, password, targetUserName);
    }
    protected IUserAuthentication getUserAuthentication(URI requestUri, String userName, String password, String targetUserName) throws UForgeException {
        /*
        * Check with IDM
        */
        ServicesContext.get().getService(IDMService.class).checkUserAuth(userName, password);
        /*
        * Grab users
        */
        User user;
        User targetUser = null;
        DbAccess db = ServicesContext.get().getService(DbAccess.class);
        try {
            Criteria userCriteria = db.getDbManager().newCriteria(User.class);
            userCriteria.add(Restrictions.eq("loginName", userName));
            user = UserAuthentication.getUser(db, userCriteria);
            if (targetUserName != null) {
                Criteria targetUserCriteria = db.getDbManager().newCriteria(User.class);
                targetUserCriteria.add(Restrictions.eq("loginName", targetUserName));
                targetUser = UserAuthentication.getUser(db, targetUserCriteria);
            }
        } catch (DBException e) {
            throw new UForgeException(UForgeException.DB_ERROR, e);
        }
        logger.debug("Basic Authentication is OK");
        return new UserAuthentication(user, targetUser);
    }
}

There are two ways to provide your authentication filter:

• modifying the webservice web.xml. You will need to modify the web.xml template by replacing the com.usharesoft.authentication.AuthenticationFilters value by your filter classname if you want only your authentication
• using the @Provider annotated class (the order can be important if the two authentication methods are used in the same request)

You can add a filter, but you cannot remove the default authentication filters, nor choose the order. To add your filter, use the following Jersey annotation:

package my.company.authentication

import javax.ws.rs.ext.Provider;
implements com.usharesoft.authentication.IAuthenticationFilter;

@Provider
class SuperAuthenticationFilter implements IAuthenticationFilter {
...
}

Allowing https Repositories with Self-Signed Certificate¶

The following command allows you to add self-signed certificates (exposed by your repositories) as trusted into the UForge server.

1. Download the SSL self-signed certificate from the server (repository) you want to populate using the following command:

echo -n | openssl s_client -connect localhost:443 | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > /tmp/cert.crt

2. Recreate the CA file on your UForge platform (containing all trusted CA):

cp /tmp/cert.crt /etc/pki/ca-trust/source/anchors/
update-ca-trust
update-ca-trust enable

3. Create a link to use the system java keystore instead of the jre default keystore:

   ln -s /etc/pki/java/cacerts /usr/java/latest/jre/lib/security/cacerts
   

The default password is changeit.

Populating Database with OS Packages¶

Open source operating system versions are taken from the official repository mirror or the UForge repository cache. Proprietary operating systems such as RedHat are not; therefore it is the responsibility of the end customer (or reseller if they have correct agreements in place to re-distribute an operating system) to have the original ISO images of the operating system in questions. Refer to Hosting Proprietary Packages.

To enable UForge to generate images based on the operating system it needs all the meta-data of the packages comprising the operating system. This meta-data includes the location in the storage of the package as well as dependency information that is used during generation. Furthermore, certain specific UShareSoft packages must be populated for this operating system.

For information specific about Windows, refer to First Installation of Windows.

In order to add an operation system in your UForge platform you must:

1. Create the OS in the organization.
2. Create the repository. This includes the official repository as well as the specific UShareSoft tool repository.
3. Link the distribution to the repository.
4. Launch spider to fill the repository with the packages.

The following is a concrete example to begin the population of CentOS 6.5 32bit:

1. In order for the following commands to be generic you can set some variables in your environment:

   . /etc/UShareSoft/uforge/uforge.conf
   ADMIN=$UFORGE_WEBSVC_LOGIN ; PASS=$UFORGE_WEBSVC_PASSWORD
   

2. Run the following CLI command in order to create the distribution:

   uforge org os add --name CentOS --arch i386 --version 6.5 -u $ADMIN -p $PASS
   

3. Enable the new operating system for the organization. The following command enables CentOS 6.5 32bit in the default organization:

   uforge org os enable --name CentOS --version 6.5 --arch i386 -u $ADMIN -p $PASS
   

4. Enable the user to use the operating system. The user must be a member of the organization. This step can be done later.:

   uforge user os enable --account root --name CentOS --version 6.5 --arch i386 -u $ADMIN -p $PASS
   

5. Create the distribution repository. The following example shows the creation of an official Centos repository. However, you can also create a repository based on the UShareSoft official repository as shown later.

   Centos 6.5 repository:

   uforge org repo create --name "CentOS 6.5 os" --repoUrl http://vault.centos.org/6.5/os/i386/ --type RPM --officiallySupported -u $ADMIN -p $PASS
   
   Success: Created repository with url [http://vault.centos.org/6.5/os/i386/] to default organization
   

   The –-name specified here is the “tagname” that will be shown in the UI when creating an appliance. The --repoUrl can be either http:// or file://

   Only use --officiallySupported for distributions that are part of the core distribution. For example, epel or vmwatools are not officially part of the distribution, therefore you should not use the variable --officiallySupported.

   The syntax of the repoURL for Debian based OSes follows that of the sources.list file.

   See https://wiki.debian.org/SourcesList and https://wiki.debian.org/Multiarch/HOWTO (section Setting up apt sources)

   Typically, a correct value for the repoURL parameter is either

   • http://httpredir.debian.org/debian jessie main
   • http://ftp.riken.go.jp/Linux/ubuntu/ precise-security multiverse restricted universe main

   Users may also want to restrict per architecture. For example:

   [arch=amd64] http://distros-repository.usharesoft.com/ubuntu/ ...
   

   http://distros-repository.usharesoft.com/ is an official public repository that users can use to populate the distributions. Official repositories such as Ubuntu and Debian periodically delete some package versions. In the http://distros-repository.usharesoft.com/ repository, package versions are never deleted. This can facilitate investigations on older systems.

   To populate the distribution using the official UShareSoft repository for Centos:

   uforge org repo create --name "CentOS 6.5 os" --repoUrl http://distros-repository.usharesoft.com/centos/6/os/x86_64 --type RPM --officiallySupported -u $ADMIN -p $PASS
   

   The following is a list for all the other distributions:

   Ubuntu (exemple 10.04)

   • http://distros-repository.usharesoft.com/ubuntu/lucid-security/mirror/bouyguestelecom.ubuntu.lafibre.info/ubuntu/ lucid multiverse restricted universe main
   • http://distros-repository.usharesoft.com/ubuntu/lucid-security/mirror/bouyguestelecom.ubuntu.lafibre.info/ubuntu/ lucid-security multiverse restricted universe main
   • http://distros-repository.usharesoft.com/ubuntu/lucid-proposed/mirror/bouyguestelecom.ubuntu.lafibre.info/ubuntu/ lucid-proposed multiverse restricted universe main
   • http://distros-repository.usharesoft.com/ubuntu/lucid-backports/mirror/bouyguestelecom.ubuntu.lafibre.info/ubuntu/ lucid-backports multiverse restricted universe main
   • http://distros-repository.usharesoft.com/ubuntu/lucid-updates/mirror/bouyguestelecom.ubuntu.lafibre.info/ubuntu/ lucid-updates multiverse restricted universe main

   Debian (exemple version 6)

   • http://distros-repository.usharesoft.com/debian/squeeze/mirror/ftp.fr.debian.org/debian/ squeeze contrib non-free main
   • http://distros-repository.usharesoft.com/debian/squeeze-updates/mirror/ftp.fr.debian.org/debian/ squeeze-updates contrib non-free main
   • http://distros-repository.usharesoft.com/debian/security/squeeze/updates/mirror/security.debian.org/ squeeze/updates main contrib non-free

   CentOS (exemple centOS 6.7)

   • http://distros-repository.usharesoft.com/centos/6.7/updates/x86_64
   • http://distros-repository.usharesoft.com/centos/6.7/extras/x86_64
   • http://distros-repository.usharesoft.com/centos/6.7/os/x86_64

   OpenSUSE (exemple version 12.2)

   http://distros-repository.usharesoft.com/usharesoft/opensuse/12.2/x86_64

   Scientific (exemple version 6.6)

   http://distros-repository.usharesoft.com/usharesoft/scientificlinux/6.6/x86_64

6. You must then add the specific UShareSoft tool repository. The repository to attach is one of the following:

   • Centos (example version 6, arch x86_64): http://distros-repository.usharesoft.com/usharesoft/centos/6/x86_64
   • Redhat: (example version 6.2, arch x86_64): http://distros-repository.usharesoft.com/usharesoft/rhel/6.2/x86_64
   • OpenSUSE: (example version 12.1, arch x86_64): http://distros-repository.usharesoft.com/usharesoft/opensuse/12.1/x86_64
   • Scientific Linux: (example version 6, arch x86_64): http://distros-repository.usharesoft.com/usharesoft/scientificlinux/6/x86_64
   • Debian: (example version 8, arch x86_64) [arch=amd64] http://distros-repository.usharesoft.com/usharesoft/debian/ jessie main
   • Ubuntu: (example version 14.04, arch x86_64) [arch=amd64] http://distros-repository.usharesoft.com/usharesoft/ubuntu/ trusty main

   For example:

   uforge org repo create --name "CentOS 6.5 os" --repoUrl http://distros-repository.usharesoft.com/usharesoft/centos/6/x86_64 --type RPM -u $ADMIN -p $PASS
   

7. Attach repository to the distribution as follows:

   uforge org repo os attach --name CentOS --arch i386 --version 6.5 --repoIds 354 -u $ADMIN -p $PASS
   

8. Populate repository packages:

   /opt/UShareSoft/uforge/cron/update_repos_pkgs.sh
   
   Note: This procedure may take a long time.
   

9. To verify if the procedure is terminated, run the following command:

   tail -f /tmp/USER_DATA/FactoryContainer/logs/repos/spider/<directory name with date>/spider.stdout
   
   Note: The procedure is terminated when you see the line: INFO  CheckForRepositoriesUpdates:275 - Entering CheckForRepositoriesUpdates->terminate()
   

10. Create OS profile based on packages (minimal, server, etc.):

    /opt/UShareSoft/uforge/bin/runjob.py sorter_low_prio -d CentOS -v 6.5 -a i386
    

11. Populate the UShareSoft packages for the new operating system:

    ARCHS=i386 DEBUG=y COS_VERS=6.5 /opt/UShareSoft/uforge/bin/exec_uploads.sh -w UssPkgs -p <uforge port> -U $ADMIN -P $PASS /tmp/DISTROS/USS/usspkgs
    

Hosting Proprietary Packages¶

Proprietary packages, such as RedHat are not delivered as part of the UForge repository. You must have the original ISO images of the operating system in questions and follow the steps below.

For example, to add a RedHat repository:

1. Mount the iso into /mnt (on the works node)
2. Create the appropriate directory layout under /tmp/USER_DATA/repos/ for example: /tmp/USER_DATA/repos/RHEL/6.5/x86_64/
3. Copy all the contents of the DVD into /tmp/USER_DATA/repos/RHEL/6.5/x86_64/
4. If the repositories does not already contain a repodata folder, you must create it inside the package directory

# cd /tmp/USER_DATA/repos/RHEL/6.5/x86_64/
# createrepo .

5. Create the repository using the UForge CLI as follows:

   uforge org repo create --name "RHEL 6.5 os" --repoUrl "http://127.0.0.1/repos/RHEL/6.5/x86_64/" --type RPM -u $ADMIN -p $PASS
   
   The –-name specified here is the “tagname” that will be shown in the UI when creating an appliance.
   The --repoUrl can be either http://
   

6. Attach repository to the distribution as follows:

   uforge org repo os attach --name RHEL --repoIds 954 -u $ADMIN -p $PASS
   

7. Populate repository packages:

   /opt/UShareSoft/uforge/cron/update_repos_pkgs.sh
   
   This procedure may take a long time.
   

8. To verify if the procedure is terminated, run the following command:

# tail -f /tmp/USER_DATA/FactoryContainer/logs/repos/spider/<directory name with date>/spider.stdout

The procedure is terminated when you see the line: // INFO  CheckForRepositoriesUpdates:275 - Entering CheckForRepositoriesUpdates->terminate()

9. Create OS profile based on packages (minimal, server, etc.):

   /opt/UShareSoft/uforge/bin/launch_distro_sorter.sh -a x86_64 -d RHEL -v 6.5
   

10. Populate the packages for the new repository:

    ARCHS=x86_64 DEBUG=y COS_VERS=6.5 /opt/UShareSoft/uforge/bin/exec_uploads.sh -w UssPkgs -p <uforge port> -U $ADMIN -P $PASS /tmp/DISTROS/USS/usspkgs
    

Populate Project Catalog (Optional)¶

UForge provides a project catalog of commonly used software that is used when constructing server templates. When a new operating system is added to UForge, there are no software components registered to the operating system in the Project Catalog. UForge bundles in a set of open source software components. If you want to associate these software components to the operating system for the project catalog, then run the following command:

# ARCHS=i386 DEBUG=y COS_VERS=5.5 /opt/UShareSoft/uforge/bin/exec_uploads.sh -w Projects -p <uforge port> -U $ADMIN -P $PASS /tmp/DISTROS/USS/projects/CATALOG-USS

Provide User Access to Operating System¶

By default, when adding a new operating system, it is not available for all users. You must explicitly provide access to the users who can access this resource. Login to one of the UForge instances and run:

uforge user os enable --name CentOS --version 5.5 --arch i386 --account <username> --url <uforge url> -u $ADMIN -p $PASS

Windows Key Mechanism¶

Windows Operating System requires a key validation. UForge generates images without a key in it. Users have 30 days to enter their key once the Appliance is booted.

UForge Database Basic Backup¶

UForge uses the PerconaDB database to store all its data. PerconaDB provides many different types of backup methods you can choose from, including:

• Doing a hot backup (for example with Percona XtraBackup)
• Copying Table files
• Delimited-Text backups
• Using the mysqldump or mysqlhotcopy commands
• Creating incremental backups by enabling the binary log
• Creating a backup from a slave
• Making backups using a file system snapshot

For more details on all these back up strategies, refer to: http://dev.mysql.com/doc/refman/5.5/en/backup-methods.html

UShareSoft uses two methods for copying the database information. All the database information is located under: /var/lib/mysql

By copying this information, you are taking a snapshot of the entire database. The first uses the rsync command to copy the current latest information of the database to another location.

# service mysql stop
# rsync -a --delete-before /var/lib/mysql root@<BACKUP-DESTINATION>
# service mysql start

As the backup destination does not change, you are creating a replication of the entire database. The rsync command only copies the incremental differences each time.

The danger here is that if during that time there is damaged data, when rsync is run then this corrupted data is copied and there is no possible way to recuperate the old data. To overcome this, UShareSoft also creates archive backups of the entire database.

# service mysql stop
# f=`date +%y%m%d`
# f=`echo "$f-mysql-backup.tgz"` #what to name backups
# tar -czf /tmp/$f /var/lib/mysql/*
# rsync -a /tmp/$f root@<BACKUP-DESTINATION>
# service mysql start

This only works if the database instance is stopped to ensure a consistent dump of the database. Otherwise you get a corrupt, inconsistent backup.

The issue with this method is if you have only one database instance, then you are effectively stopping your service to do the backup. To overcome this you need to use replication, for example master-slave.

Basic Restore¶

Restoring the database is a simple copy using rsync back to the database directory. Note the use of slashes (/ ) is important.

# service mysql stop
# rsync -a --delete-before root@<BACKUP-DESTINATION>/mysql/ /var/lib/mysql
# service mysql start

Using Master-Slave Replication for Database Backup¶

To ensure consistent backups of the data and to limit the impact of the actual backup process on the service performance, a common approach is to use Master-Slave replication. This is an easy way to provide a complete running copy of the data on another database instance (called the slave). Consequently you can then stop the slave instanceto do the backups while leaving the other instance (the master) to continue providing the database service. Master-slave replication is also the first implementation of high-availability.

The configuration of master-slave replication is out of scope of this document, but we recommend the following reading:

• How to Set Up Replication, MySQL documentation
• High Availability MySQL Cookbook
• MySQL High Availability by O’Reilly

You can now safely run the same commands provided in section “Doing a Basic Backup” on the slave database instance. To automate the entire process, a script can be written and executed by a cron job at the frequency you wish to backup the database (nightly backups are recommended).

If you want to add high-availability, then UShareSoft recommends using MySQL Cluster. This is a separate MySQL product that is not distributed with UForge.

User Data Backup¶

UForge also stores information that is uploaded by the users of the platform. These are:

• packages, binaries and files that are uploaded in My Software or Projects
• images (photos, appliance logos etc)
• boot scripts
• licenses (attached to projects and My Software)
• UForge Studio packages

All this information is stored in the following directory: /tmp/USER_DATA

Like the database, this is important information that must be backed up on a regular basis. The same mechanism can be used for back up as the database, namely using rsync as highlighted in UForge Database Basic Backup, or disk mirroring (RAID), or both.

LDAP Backup and Restore¶

You can backup your data without stopping the server using:

/opt/OpenDJ/bin/backup -a -c -d /tmp/dir_to_backup

Note that the example above uses /tmp for the backup; however, we recommend you use a mounted disk, SAN or NAS to store your backup.

To restore the latest backup, you must first stop the LDAP service:

service OpenDJ stop

Then run the restore:

/opt/OpenDJ/bin/restore -d /tmp/dir_to_backup/userRoot
/opt/OpenDJ/bin/restore -d /tmp/dir_to_backup/tasks
/opt/OpenDJ/bin/restore -d /tmp/dir_to_backup/config
/opt/OpenDJ/bin/restore -d /tmp/dir_to_backup/schema

To restart the LDAP service:

service OpenDJ start

IDM Service Backup and Restore¶

UForge uses Syncope for identity management. Note that the following example uses /tmp for the backup; however, we recommend you use a mounted disk, SAN or NAS to store your backup.

Backup Overview Guidelines¶

There are two zones of UForge data that should be backed up:

• UForge database service.
• UForge user data (user uploaded software etc)

Database replication and backup are sometimes confused as achieving the same goal. Many people believe that by having replication, the data within the database is being stored elsewhere and therefore in the event of a serious problem, the data can be recovered. However, with replication, any accidental changes or deletions are also replicated to the other systems.

Database replication is meant for high-availability of your service, in other words building a redundant database service. If a problem occurs with one database instance, then having a second database with the data replicated, this instance can continue providing the database service (even if the service is degraded).

Database backups is used to take a snapshot of the database data (either a complete or incremental snapshot) and storing this information in an archive.

When thinking about your database strategy, you should consider the following goals:

• The backup should be an internally consistent snapshot (this may seem obvious, but if you do not lock the database or turn the database off before doing the snapshot then the data may be inconsistent).
• Keep the service running during the backup (in production systems this will be mandatory, however for less-critical platforms this may not be a necessary goal)
• Make the backup automated (via cron or using some 3rd party tools)

Backup Recommendations¶

Here are some general recommendations and guidelines when doing database backup.

Never Back Up Databases to Local Disk

If the database server crashes, especially due to a hardware problem or a severe OS problem, the local drives may not be available. In the event of a hardware disaster, if the archives and current copy is on the shared filesystem allowing someone to quickly build a new server and start doing restores while resuscitating the server.

Back up Databases to a Fileshare, then Back the Share to Tape

Tape drives these days are fast enough that the vendors like to say DBAs should go straight to tape, and they are technically right: tape backup & restore speed is not a bottleneck. However, there is a limited number of drives available. This, however, gives you an extra layer of backup protection in case something goes wrong with the shared filesystem.

Back Up to a Different NAS/SAN

This is not possible for everyone, however, in extremely rare occasions where the production NAS/SAN does go down then at least the backup array was not affected as it is on a different NAS/SAN than the production system.

Consider Raid 10 SATA

Depending on the backup windows, multiple database servers may be writing backups to that same share simultaneously. Raid 10 gives better write performance than raid 5, (using fiber channel backup drives is even better but cost-prohibitive). Raid 10 on SATA gets a good balance of cost versus backup throughput.

Getting Professional Services for Database Backup¶

UShareSoft are partners with SkySQL who give professional advice on database high-availability and backup solutions. Contact UShareSoft if you wish to be introduced to SkySQL.

Starting and Stopping the Application Server¶

Glassfish is registered as an operating system service. Each time a web service node is rebooted, the application server is restarted automatically as part of the node boot sequence. To manually stop or start the web service you must be the unix root user of the node.

# service glassfish stop

# service glassfish start

# service glassfish restart

Starting and Stopping the Database¶

The database is registered as an operating system service. Each time a database node is rebooted, PerconaDB is restarted automatically as part of the node boot sequence. To manually stop or start the database you must be the unix root user of the node. Log in to the database node as root:

# ssh root@<ip address of the node>

# service mysql stop

# service mysql start

# service mysql restart

Viewing The Supported OSes¶

All the open source operating system versions are delivered as part of the UForge repository. Proprietary operating systems are not.

To get the complete list of the currently supported operating systems on the UForge platform use the command uforge os list.

Login to one of the UForge instances
# uforge os list -u $ADMIN -p $PASS
Getting operating systems ...
Success: Found the following operating systems
+----------------+-----------------+--------------+--------+---------+---------+------------------+
| Distribution   | Version         | Architecture | Access | Visible | Default | Release Date     |
+----------------+-----------------+--------------+--------+---------+---------+------------------+
| CentOS         | 5               | i386         |   X    |    X    |         | NK               |
| CentOS         | 5.3             | i386         |   X    |    X    |         | 2009-03-17       |
| CentOS         | 5.3             | x86_64       |   X    |    X    |         | 2009-03-18       |
| CentOS         | 5.4             | i386         |   X    |    X    |         | 2009-10-01       |
| CentOS         | 5.4             | x86_64       |   X    |    X    |         | 2009-10-01       |
| CentOS         | 5.5             | i386         |   X    |    X    |         | 2010-04-27       |
| CentOS         | 5.5             | x86_64       |   X    |    X    |         | 2010-04-27       |
| CentOS         | 5.6             | i386         |   X    |    X    |         | 2011-03-07       |
| CentOS         | 5.6             | x86_64       |   X    |    X    |         | 2011-03-22       |
| CentOS         | 5.7             | i386         |   X    |    X    |    X    | 2011-08-29       |
.... rest omitted for clarity

All the open source operating system versions are delivered as part of the UForge repository. Proprietary operating systems are not; therefore it is the responsibility of the end customer (or reseller if they have correct agreements in place to re-distribute an operating system) to have the original ISO images of the operating system in questions.

Viewing the Enabled OSes¶

To get a list of the operating systems that are currently enabled on your UForge platform use the command uforge org os list.

Login to one of the UForge instances
# uforge org os list -u $ADMIN -p $PASS
Getting operating systems ...
Success: Found the following operating systems
+----------------+-----------------+--------------+--------+---------+---------+------------------+
| Distribution   | Version         | Architecture | Access | Visible | Default | Release Date     |
+----------------+-----------------+--------------+--------+---------+---------+------------------+
| CentOS         | 6.3             | i386         |   X    |         |         | 2012-07-01       |
| CentOS         | 6.3             | x86_64       |   X    |         |         | 2012-06-26       |
| CentOS         | 6.4             | i386         |   X    |         |         | 2013-03-01       |
| CentOS         | 6.4             | x86_64       |   X    |    X    |         | 2013-03-01       |
.... rest omitted for clarity

Older operating system versions (that for example have been EOL’d) or proprietary operating systems such as RedHat Enterprise Linux are not automatically populated at the installation phase. Population of such operating system versions must be done manually after the initial installation of UForge is complete.

Adding an OS to an Organization¶

Before adding an OS to the organization you must retrieve data from the UShareSoft repository. For more information refer to Populating Database with OS Packages.

In order to add an OS to an organization you must do the following:

1. Add the distribution to the organization.
2. Create the repositories.
3. Attach the repository to the distribution.
4. You will then need to launch Spider to fill the repositories.

This must be done for each version of an OS. For example CentOS 6.5 i386. It is not possible to do this for all CentOS versions at once.

For example, to add CentOS 6.5 i386 to the default org:

In order to add the OS to a specific distribution, you will need to specify --org <value> for each of the commands in the steps below.

1. Add the distribution to the organization, using the official name and version.

# uforge org os add --name CentOS --version 6.5 --arch i386 -u $ADMIN -p $PASS
Getting default organization ...
Success: Add operating system OK

2. Create the repositories.

# uforge org repo create --name CentOSplus --repoUrl http://vault.centos.org/6.5/centosplus/i386 --type RPM -u $ADMIN -p $PASS
Getting default organization ...
Success: Created repository with url [http://vault.centos.org/6.5/centosplus/i386] to default organization
+------+----------------+------------+---------------------------------------------+-------+
|   Id | Off. Supported | Name       | Url                                         | type  |
+------+----------------+------------+---------------------------------------------+-------+
|  355 |                | CentOSplus | http://vault.centos.org/6.5/centosplus/i386 | RPM   |

3. Attach the repository to the distribution

# uforge org repo os attach --name CentOS --version 6.5 --arch i386 --repoId 355 -u $ADMIN -p $PASS
Getting default organization ...
Success: Attach distribution to repository [355]

4. Launch Spider and other population steps. Refer to Populating Database with OS Packages.

Removing OSes and Distributions¶

You cannot remove an OS from an organization once added. You can only disable it, in which case it can no longer be used. To disable a distribution, for example CentOS for all users of an organization you can specify only the OS name, in which case all the versions will be removed:

# uforge org os disable --name CentOS -u $ADMIN -p $PASS

If you only want to remove a specific version of a distribution (for example CentOS 5), run:

# uforge org os disable --name CentOS --version 5 -u $ADMIN -p $PASS

Creating Custom OS Profiles¶

UShareSoft provides a set of OS profiles. If you want to create another OS profile, you can create one using UForge’s graphical user interface.

To create a new OS profile:

1. Under the Administration tab, click OS Profiles.

2. If you are an administrator to more than one organization, then you can choose the organization to administer from the drop-down menu.

3. Double-click on the operating system you want to administer. This will provide the current list of profiles this operating system has.

4. Select the profile which will serve as the base for your custom OS profile and click create.

5. Enter your profile name and click create.

6. Enter a description (mandatory).

7. Select the package(s) you want to add to your OS profile and click save. You can search for the package you want to add. The packages that you can add are listed in the top list. The bottom list is the list of packages that are currently part of the profile.

8. Click Save.

Editing Custom OS Profiles¶

If you have created a custom OS profile, you can edit it at any time. You cannot modify a profile provided by UShareSoft.

To edit your OS profile:

1. Under the Administration tab, click OS Profiles.
2. If you are an administrator to more than one organization, then you can choose the organization to administer from the drop-down menu.
3. Click on the operating system you want to administer. This will provide the current list of profiles this operating system has.
4. Click on the profile you want to edit.
5. You can edit the name and description from the Overview page.
6. To modify the packages included in your profile, click OS Packages. The packages that you can add are listed in the top list. The bottom list is the list of packages that are currently part of the profile. Select the package(s) you want to add or remove to your OS profile and click save. You can search for the package you want to add.
7. Click Save.

Windows and UForge¶

Within UForge Windows is treated differently from other Linux/UNIX operating systems. In fact, Windows is not bundled with packages. Consequently, it is not possible to create standard (package based) OS Profile as for all the other supported distributions.

Instead, UForge uses a Golden Image as a profile. A Golden Image is an image that has been generated by UShareSoft or by the customer (see Creating a Golden Image) that contains the basic installation of the Windows version and some extra files. You can generate Golden Images at any time.

A Golden Image can be between 5 to 10 Gb, depending on the selected version.

This chapter describes how to create your own Windows Golden Images. Windows Golden Images need to be created in order to create Windows templates. If you want to incorporate a Windows update, then you need to create and install a new set of Golden Images. UShareSoft has a tool called the Golden Creator and can provide Golden Images. This chapter assumes you want to create the Golden Image yourself.

org golden list --name Windows --arch x86_64 --version Server2008R2

org golden create --name Windows --arch x86_64 --version Server2008R2 --language English --edition Standard --type Full --goldenDate 2012-10-19 --goldenName Windows_2008R2_Standard_Full_2012-10-19.raw.gz

Base dir = Windows/releases/Server2008R2/x86_64/

{Language}/{Edition}/{Type}/{generation date}(YYYY-MM-DD)/goldenImagePathCompressedInGz

Managing the Project Catalog¶

A Project Catalog is a collection of software components that are available for UForge users to use when building their server templates. A project is one software component. A project includes files, binaries or native packages and may have an EULA (End User License Agreement).

Each organization within the UForge platform has a project catalog, and each member of the organization has access to the project catalog, allowing them to add any of the projects to their server templates. The contents of the project catalog, however, can only be updated and managed by the administrators of the organization where the project catalog belongs. An organization administrator can:

• add new projects to the catalog
• update existing projects to the catalog
• delete a project. The project will no longer appear in the project catalog, however it is not permanently deleted. This ensures that any existing templates that use the project can still generate images correctly.

You can also create custom OS profiles to include specific packages to an existing (standard) OS profile. See Creating Custom OS Profiles.

Creating and Managing Categories¶

Categories are used to organize projects. Users can use categories in order to filter projects in the appliance library.

Creating and Managing Milestones¶

Milestones are used as a marker for a specific event, such as beta or GA for example. They appear on the GUI under OS package updates.

In the figure above, the M indicates a Milestone. For CentOS, this is the versions (6.1, 6.2 etc). Milestones can be customized by the UForge administrator using the command line interface.

To create or manage milestones using the CLI, use the command uforge os.

The available commands are:

• milestone add
• milestone list
• milestone modify
• milestone remove

In order to create a milestone called “beta” for Debian, run:

# uforge os milestone add --dname Debian --darch i386 --dversion 6 --date 2014-01-01 12:00:00 --name beta –u $ADMIN -p $PASS

Managing User Accounts¶

When managing user accounts, the administrator must have administration privileges for the organization where the user account is part of or where the member will be created.

# uforge user create --account kermit --code <subscriptionProfileCode> --email kermit@usharesoft.com --url https://uforge.usharesoft.com:443 -u $ADMIN -p $PASS

# uforge user disable --account kermit –-url https://uforge.usharesoft.com:443 -u $ADMIN -p $PASS
Getting user [kermit] ...
Success: User kermit has been de-activated

Creating User Groups¶

As an administrator you can create user groups to group users that will have the same publishing rights for Marketplace. For example rather than assign publishing rights to 10 members of a group individually, you can create a user group (“MyGroup”), and assign the publishing rights to the group. The users can then publish to the Marketplace as “MyGroup”.

To create a user group, use the command uforge usergrp create.

For example, run:

uforge usergrp create --user $ADMIN --password $PASS --email kermit@usharesoft.com --name MyGroup

In the example above, the argument --user is the account of the administrator. The argument --name is the name of the user group you are creating.

uforge usergrp user add --user $ADMIN --password $PASS --name MyGroup --accounts userA userB userC

uforge usergrp list --user $ADMIN --password $PASS

RBAC Overview¶

Access to the various services of the UForge platform is enforced by roles. Each role contains one or more entitlements that define the access to one or more services or permissions for various actions.

uforge role list -u $ADMIN -p $PASS
Getting all the roles for the default organization ...
+--------------------------+----------------------------------------------------------------------------------+
| Name                     | Description                                                                      |
+--------------------------+----------------------------------------------------------------------------------+
| admin                    | Provides organization administration rights.  Includes managing the organizations project catalog; os profiles and |
|                          | user accounts.                                                                   |
+ Entitlements ------------------+----------------------------------------------------------------------------+
| marketplace_access       | used to determine whether to allow a user to interact with the marketplace (note, will be able to retrieve  |
|                          | templates + template info, but voting, adding a comment, import, follow etc forbidden)  |
| org_administrate         | Access to manage the entitlements list available for an organization.            |
| org_formats_administrate | Access to manage the generation formats available for an organization.           |
| org_members_administrate | Access to manage user accounts for an organization.                              |
| org_os_administrate      | Access to manage the operating systems available for an organization.            |
| org_os_profiles_administrate| Access to manage the os profiles available for an organization.               |
| org_projects_administrate| Access to manage the project catalog for an organization.                        |
| user_create              | Access to create user accounts in UForge.                                        |
+--------------------------+----------------------------------------------------------------------------------+
Found 15 role(s)
| apiuser                  | Allows the user to communicate with UForge via the APIs.                         |
+ Entitlements ------------+----------------------------------------------------------------------------------+
| api_key_access           | Access to UForge APIs.                                                           |.... rest omitted for clarity

uforge entitlement list -u $ADMIN -p $PASS

uforge role list --org usharesoft -u $ADMIN -p $PASS

uforge role create --name newrole --description “description of new role” -u $ADMIN -p $PASS

uforge role entitlement add --name newrole --entitlements appliance_create studio_access -u $ADMIN -p $PASS

uforge role entitlement remove --name newrole --entitlements studio_access -u $ADMIN -p $PASS

uforge role create --name newrole --description “description of new role” --entitlements appliance_create studio_access -u $ADMIN -p $PASS

uforge user role list --account <username> -u $ADMIN -p $PASS

uforge user role add --account <username> --roles newrole -u $ADMIN -p $PASS

uforge user role add --account <username> --roles role1 role2 -u $ADMIN -p $PASS

uforge role delete --account <username> --roles roleA -u $ADMIN -p $PASS

Usage: uforge subscription <command> [options] [args]

Commands:
        admin add                      : Add a user as a subscription profile administrator.
        admin remove                   : Remove a user as a subscription profile administrator.
        create                         : Create a new subscription profile within an organization.
        delete                         : Delete a subscription profile from an organization.
        disable                        : Disables a subscription profile within an organization    (cannot be used to create users).
        enable                         : Activates or enables a subscription profile within an organization.
        format add                     : Add an image format to a subscription profile.
        format remove                  : Remove an image format to a subscription profile.
        info                           : Get detailed information on a subscription profile within an organization.
        list                           : List all the subscription profiles for a given organization.  If no organization is provided the default organization is used.
        os add                         : Add an operating system to a subscription profile.
        os remove                      : Remove an operating system from a subscription profile.
        quota update                   : Updates a subscription profile quota
        role add                       : Add a role to a subscription profile
        role remove                    : Remove a role to a subscription profile
        update                         : Updates an existing subscription profile.

...removed options for clarity

uforge subscription admin add --admin kermit --name profileA --org usharesoft -u $ADMIN -p $PASS

uforge subscription disable --name profileA -u $ADMIN -p $PASS

Granting a User Administrator Rights¶

There are two steps in granting a user Administrator privileges; you must:

1. Give the user the administrator role. This only indicates that the user CAN be an administrator, but does not specify for which organizations:

   uforge user role add --account <username> --roles admin -u $ADMIN -p $PASS
   

2. Assign the user as administrator to a specific organization. If no organization is provided, then the default organization is used:

   uforge user admin promote –-account <username> --org <org name> -u $ADMIN -p $PASS
   

Setting Quotas¶

You can set a number of quotas for a user account using the command: uforge user quota modify.

Setting quotas allows you to limit the user’s access to UForge based on one (or several) of the following criteria:

• number of appliances created (includes import from marketplace, collaboration workspace and scans)
• number of images generated (includes image generation from a scan or from the marketplace)
• diskusage in bytes (includes storage of mysoftware uploads, bootscripts, image generations, scans)
• number of scans for migration (includes initial scan and incremental scans)

You can set the quotas to refresh once a month using the argument --frequency. You can set the frequency to:

• monthly: the quota counter will be reset every month. The day of the reset is based on the date of the user creation (and not the date when the limit is set).
• none: once the quota is reached it will not be reset automatically (it can however be increased manually).

uforge user quota list --user $ADMIN --account <username> --password $PASS

$ uforge user quota list --user $ADMIN --account <username> --password $PASS
Getting user [user] ...

+------------------+--------------+------------+------------+-------------------------------+
| Type             |     Consumed |      Limit | Frequency  | Renewal date                  |
+------------------+--------------+------------+------------+-------------------------------+
| appliance        |            1 |  unlimited |            | -                             |
| diskusage        |          0.0 |  unlimited |            | -                             |
| generation       |            0 |  unlimited |            | -                             |
| scan             |            0 |  unlimited |            | -                             |
+------------------+--------------+------------+------------+-------------------------------+
Found 4 formats

uforge user quota modify --user $ADMIN --password $PASS --account kermit --type appliance --limit 10 --frequency monthly

uforge user quota modify --user $ADMIN --password $PASS --account kermit --type generation --limit 10 --frequency monthly

uforge user quota modify --user $ADMIN --password $PASS --account kermit --type scan --limit 5 --frequency monthly

UFORGE_SCAN_OVERLAY_MAX_SIZE = maximum size in octets

UFORGE_SCAN_OVERLAY_MAX_SIZE=10737418240

uforge user quota modify --user $ADMIN --account user --type diskusage --limit 10737418240 --password $PASS

uforge user quota list --user $ADMIN --account <username> --password $PASS
Getting user [user] ...

+------------------+--------------+------------+------------+-------------------------------+
| Type             |     Consumed |      Limit | Frequency  | Renewal date                  |
+------------------+--------------+------------+------------+-------------------------------+
| appliance        |            1 |  unlimited |            | -                             |
| diskusage        |          0.0 |      10 GB |            | -                             |
| generation       |            0 |  unlimited |            | -                             |
| scan             |            0 |  unlimited |            | -                             |
+------------------+--------------+------------+------------+-------------------------------+
Found 4 formats

uforge user quota modify --user $ADMIN --account user --type scan --unlimited --password $PASS

Managing Access to Formats and OSes¶

Each user account can be configured to have access to certain operating systems and image formats that are enabled in the organization. When a user account is created, the organization’s default operating systems and image formats are automatically added. The administrator can then add or remove operating systems and image formats for a specific user account using the command-line interface.

$ uforge user format list --account kermit --url https://uforge.usharesoft.com:443 -u $ADMIN -p $PASS
Getting user [kermit] ...
Success: User [kermit] can have access to the following image formats in the default organization
+------------------+--------+
| Format           | Access |
+------------------+--------+
| abiquo           |   X    |
| ami              |   X    |
| cloudburstvmware |        |
| cloudcomova      |   X    |
| cloudcomqcow2    |   X    |
| cloudcomvhd      |   X    |
| cloudsigmaraw    |        |
| emi-kvm          |   X    |
| emi-xen          |   X    |
| esx              |   X    |
| hyper-v          |   X    |
| ISO              |   X    |
| kvm              |   X    |
| nimbulaesx       |   X    |
| nimbulakvm       |   X    |
| openstack        |   X    |
| ovf              |   X    |
| qcow2            |   X    |
| raw              |   X    |
| vbox             |   X    |
| vhd              |   X    |
| vmware           |   X    |
| xen              |   X    |
+------------------+--------+

$ uforge user format disable --format ovf qcow2 vbox --account kermit --url https://uforge.usharesoft.com:443 -u $ADMIN -p $PASS
Getting user [kermit] ...
Success: Disabled 3 image formats for user [kermit]
Success: Disabled image formats:
+------------------+--------+
| Format           | Access |
+------------------+--------+
| ovf              |        |
| qcow2            |        |
| vbox             |        |
+------------------+--------+

$ uforge user os list --account <username> -u $ADMIN -p $PASS

uforge user os enable --account <username> --name CentOS
uforge user os disable --account <username> --name CentOS

uforge user os enable --account <username> --name CentOS --version 5.8
uforge user os disable --account <username> --name CentOS --version 5.8

uforge user os enable --account <username> --name CentOS --version 5.8 --arch i386
uforge user os disable --account <username> --name CentOS --version 5.8 --arch i386

Allowing a User to Share to the Marketplace¶

You can add individual users or groups of users as publishers to the Marketplace. Only users/groups that you have added will be able to publish to the Marketplace.

There are two steps in order to allow a user to share appliances to the Marketplace. You must:

1. Ensure the user has the entitlement marketplace_share as part of one of the assigned roles. See details below.
2. Add the user to the organization publisher list.

uforge user role list --account <username> -u $ADMIN -p $PASS

uforge user role info --name <rolename> -u $ADMIN -p $PASS

uforge publish add --user $ADMIN --password $PASS --accounts MyGroup userA userB

Granting a User API Access¶

Each user account can be configured to have access to the UForge APIs. This allows the user to automate the creation of appliances.

To use UForge APIs, an API key pair (public and secret keys) must be used as part of the communication. When a user account is enabled, an API key pair is created automatically. The administrator may also grant the user to have more than one set of API key pairs. This allows the user to create and manage multiple API key pairs.

To grant API access to a user account you must create a role to which you will assign the entitlement api_key_access.

1. Create the new role:

   uforge role create --name newrole --entitlement api_key_access -u $ADMIN -p $PASS
   

2. Assign this new role to the user:

   uforge user role add --name new role --account kermit -u $ADMIN -p $PASS
   

3. Optionally you can set the number of API keys:

$ uforge user api quota --apimax 5 --account kermit -u $ADMIN -p $PASS
Getting user [kermit] ...
Success: User kermit now has an API Key Quota of [5]

To disable API access simply remove the entitlement api_key_access:

uforge user role remove --name newrole --account kermit -u $ADMIN -p $PASS

Granting a User Supervisor Rights¶

If you want to allow a user to login to UForge as another user, you must grant the user supervisor rights. To do so, use the entitlement supervisor_access. You can either:

• add the entitlement to an existing role (note this will give supervisor rights to ALL the users with that role)
• create a new role with the supervisor access.

It is probably safer to create a new “supervisor” role and add the supervisor rights, to limit the number of users that can access all the user accounts in the organization.

1. To create a new role, refer to Creating and Updating User Roles.

2. Add this new supervisor role to the user who will be acting as “supervisor”; see Adding a Role to a User.

3. If the user is not already an administrator, you will need to promote the user as an administrator of the organization for which supervisor rights are assigned:

   uforge user admin promote --account kermit --org MyOrg -u $ADMIN -p $PASS
   

If no organization is provided, then the default organization is used. If you prefer to add supervisor access to an existing role (in this case “admin”) run the following command:

uforge role entitlement add --name admin --entitlements supervisor_access -u $ADMIN -p $PASS

Viewing the Web Service Logs¶

All the web service logs can be found in the domain directory of the Glassfish application server. The web service uses the log4j logger. You can change the log level of the web service resources for debugging purposes. To view the logs:

Log in to the web service node as root:

ssh root@<ip address of the node>
cd /var/log/glassfish/
tail -f server.log

To change the log level of the web service:

1. Log in to the web service node as root

ssh root@<ip address of the node>

cd /var/log/glassfish/
vi log4j.properties

2. Update the logging level for each resource you wish by using the following keywords: info|warn|debug
3. Force glassfish to reload

touch /opt/GlassFish/glassfish/domains/uforge/applications/uForgeWebService .reload

4. Restart the Web Service

service glassfish restart

Viewing Current Jobs in the Scheduler¶

To view the scheduler’s current queue, log in to the oar scheduler node as root and run the command oarstat:

# oarstat
Job id     Name           User           Submission Date     S Queue
---------- -------------- -------------- ------------------- - ----------
5725       4825           glassfish      2012-05-01 18:53:32 R default

This provides information on the jobs currently being executed as well as the jobs that are scheduled to be executed once a resource is free.

To view more details of a specific job, log in to the oar scheduler node as root and run the command oarstat and specify the JOB_ID:

# oarstat --job 5725 –-full
Job_Id: 5725
    job_array_id = 5725
    job_array_index = 1
    name = 4825
    project = [% 62, Installing distribution]
    owner = glassfish
    state = Running
    wanted_resources = -l "{type = 'default'}/resource_id=1,walltime=2:0:0"
    types =
    dependencies =
    assigned_resources = 51
    assigned_hostnames = vm
    queue = default
    command = /tmp/USER_DATA/FactoryContainer/images/4825/oar/ISO_4825.sh
    launchingDirectory = /tmp/USER_DATA/FactoryContainer/images/4825/oar
    jobType = PASSIVE
    properties = (nature=6) AND desktop_computing = 'NO'
    reservation = None
    walltime = 2:0:0
    submissionTime = 2012-05-01 18:53:32
    startTime = 2012-05-01 18:53:33
    cpuset_name = glassfish_5725
    initial_request = oarsub -d /tmp/USER_DATA/FactoryContainer/images/4825/oar -E oar_image_job4825.stderr -O oar_image_job4825.stdout -n 4825 --project null --checkpoint=1 --signal=15 -p nature=6 /tmp/USER_DATA/FactoryContainer/images/4825/oar/ISO_4825.sh
    message = FIFO scheduling OK
    scheduledStart = 2012-05-01 18:53:33
    resubmit_job_id = 0
    events =

Viewing the Logs of a Job¶

The main logs of OAR are stored in: /var/log/oar.log Each job launched on the OAR cluster, whether it be an image generation or publish to a cloud, logs are stored for the job. These include all the traces and error information during the execution of the job. Each job has a unique ID provided to it, which can be recuperated using the “oarstat” command as shown in Viewing Current Jobs in the Scheduler.

For jobs that generate an image, the log files are stored under: cd <user data mount point>/FactoryContainer/images/<job_name>

For example:

# oarstat
Job id     Name           User           Submission Date     S Queue
---------- -------------- -------------- ------------------- - ----------
5725       4825           glassfish      2012-05-01 18:53:32 R default

The directory will be:

# cd <user data mount point>/FactoryContainer/images/4825

Logs for jobs that publish an image to a specific cloud are stored in a sub-directory of the generated image directory. So for example if a user generates an Amazon AMI image, then publishes the AMI image to Amazon, the directory structure created is:

/<user data mount point>/FactoryContainer/images
                |
                |
                |-- generated image logs dir --> 4825
                                              |
                                              |
                                              |-- published image logs dir --> publish_<job_name>

To view the logs of a job, log in to the oar scheduler node as root:

# cd /<user data mount point>/FactoryContainer/images/<job_name>/oar

so for example

# cd /tmp/USER_DATA/FactoryContainer/images/4825/oar
# ls -al
total 376
drwxr-xr-x 2 glassfish glassfish   4096 Apr 30 18:21 .
drwxr-xr-x 6 glassfish glassfish   4096 Apr 30 18:22 ..
-rwxr-xr-x 1 glassfish glassfish    980 Apr 30 18:15 ISO_4825.sh
-rwxr-xr-x 1 glassfish glassfish   1088 Apr 30 18:15 cmd_4825.sh
-rwxrwxrwx 1 glassfish glassfish    300 Apr 30 18:18 oar_image_job4825.stderr
-rwxrwxrwx 1 glassfish glassfish 360500 Apr 30 18:21 oar_image_job4825.stdout

To check for suspicious jobs you can run:

# oarnodes | grep -i suspected

Using Supervisor Mode¶

UForge allows you to login as another user if you have supervisor access. Supervisor access rights are assigned by the UForge administrator. Once you have supervisor rights, you will see the option supervisor access in the top right of the UForge GUI banner.

To log in as another user with supervisor mode:

1. Click on supervisor mode in the top right of the UForge banner.
2. In the login screen, enter the name of the user you want to log in as. You will note that you do not need to enter a password.

Using the CLI Tool¶

There are two methods to use the command-line tool:

• interactive mode. In this case, you launch the UForge CLI as follows: uforge -u <user> -p <password> -U https://uforge.usharesoft.com/api
• by individual commands, assuming you know the command you want to launch. For example to list user information for root: uforge -u root -p <password> -U https://uforge.usharesoft.com/api user info –account root

Command-line Tool Presentation

The UForge AppCenter command-line tool has the form:

Usage: uforge <target> <command> [options][args]

Where <target> is one of the following:

entitlement           Administration of all the entitlements in UForge for
                      RBAC
images                Administer generated images for a user
org                   Organization administration
                      (list/info/create/update/delete etc)
os                    Administer operating systems/distributions (list/info
                      etc)
pimages               Administer published images for a user
role                  Manage platform roles
subscription          Manage subscription profiles : list profile, create
                      profiles, update profiles
template              Administer templates for a user
                      (list/info/create/delete/generate/share etc)
user                  User's administration (list/info/create/update/delete
                      etc)
usergrp               user group administration (list/info/create/delete
                      etc)

optional arguments:
  -U URL, --url URL     the server URL endpoint to use
  -u USER, --user USER  the user name used to authenticate to the server
  -p PASSWORD, --password PASSWORD
                        the password used to authenticate to the server
  -v                    displays the current version of the uforge-cli tool
  -h, --help            show this help message and exit
  -k PUBLICKEY, --publickey PUBLICKEY
                        public API key to use for this request. Default: no
                        default
  -s SECRETKEY, --secretkey SECRETKEY
                        secret API key to use for this request. Default: no
                        default
  -c, --no-check-certificate
                        Don't check the server certificate against the
                        available certificate authorities

Creating Dedicated Image Directory¶

If you plan to include your own logos and images when customizing Portal, you should create a sub-directory under: /var/opt/UShareSoft/uforge-client/gwt/uforge/templates/images

For example, place all your logos and images under: /var/opt/UShareSoft/uforge-client/gwt/uforge/templates/images/myCompany

In all of the following sections, if you update logos and images, use your new path. For example:

<c:signInLogoUrl>images/signInLogo.png</c:signInLogoUrl>

Must be changed to:

<c:signInLogoUrl>images/myCompany/signInLogo.png</c:signInLogoUrl>

Customizing the Footer¶

UForge Portal allows you to customize the information that appears in the footer. The config.xml file provides two sections to modify this info:

• <c:client>
• <c:footer>

The following figure illustrates a sample footer.

<c:version>3.4.2</c:version>

<c:showUForgeUrl>false</c:showUForgeUrl>

<c:copyright>Copyright © 2007-2014</c:copyright>

<c:footerItem>
   <c:title>twitter</c:title>
   <c:link>https:twitter.com/usharesoft</c:link>
</c:footerItem>

<c:footerItem>
   <c:title>terms of use</c:title>
   <c:link>https//www.usharesoft.com/about/terms-of-use.html</c:link>
</c:footerItem>
<c:footerItem>
   <c:title>privacy policy</c:title>
   <c:link>https//www.usharesoft.com/about/privacy-policy.html</c:link>
</c:footerItem>

Modifying the Sign-In and Sign-Up Page¶

You can modify a few elements on the sign-in and sign-up page.

The following figure shows a sample Sign-in page, illustrating the elements that can be modified.

You can modify the logo that appears on the sign-in and sign-up page in section <c:client>:

<c:signInLogoUrl>images/signInLogo.png</c:signInLogoUrl>

You can also modify the text that appears when you scroll over the logo, as well as the link the user is directed to when clicking on the link in section <c:client>:

<c:signInLogoTitle>Go to UShareSoft.com</c:signInLogoTitle>
<c:signInLogoLink>http://usharesoft.com</c:signInLogoLink>

You can modify the page you are directed to when you click on “Need an account? Sign up”, in section <c:client>:

<c:externalSignUpUrl>http://www.usharesoft.com/products/signup</c:externalSignUpUrl>

Modifying the Title of the UForge GUI¶

You can modify the title that appears in the browser when you open the portal in section <c:client>:

<c:title>UForgePortal</c:title>

Hiding Option to Modify Password¶

You can choose to hide the option to modify the password on the My Account page. To do so set the option to “false” in section <c:client>:

<c:showChangePassword>false</c:showChangePassword>

This is useful if you have your own authentication mechanism and do not want UForge users to be able to change the password in UForge, since their credentials are managed somewhere else.

Modifying the Banner¶

You can modify several elements of the banner.

The following figure shows a sample banner, illustrating the elements that can be modified.

You can modify the logo on the left in section <c:client>:

<c:headerLogoUrl>images/headerLogo.png</c:headerLogoUrl>

You can also modify the text that appears when you scroll over the logo, as well as the link the user is directed to when clicking on the link in section <c:client>:

<c:headerLogoTitle>Go to UShareSoft.com</c:headerLogoTitle>
<c:headerLogoLink>http://usharesoft.com</c:headerLogoLink>

You can modify the image that appears in the middle of the banner, in section <c:client>:

<c:bannerUrl>images/banner.png</c:bannerUrl>

You can also modify the text that appears when you scroll over the banner image, as well as the link the user is directed to when clicking on the link in section <c:client>:

<c:bannerTitle>Go to sign up form</c:bannerTitle>
<c:bannerLink>http://usharesoft.com/products/signup/</c:bannerLink>

Modifying the Logo when Signed In¶

You can modify the logo that appears at the top of the page once a user is signed in. In section <c:client>:

<c:headerSignedInLogoUrl>images/headerSignedInLogo.png</c:headerSignedInLogoUrl>

You can also modify the text that appears when you scroll over the logo, as well as the link the user is directed to when clicking on the link in section <c:client>:

<c:headerSignedInLogoTitle>Go to UShareSoft.com</c:headerSignedInLogoTitle>
<c:headerSignedInLogoLink>http://usharesoft.com</c:headerSignedInLogoLink>

Restricting Formats¶

UForge Portal allows users to generate the templates provided to all the formats the user has access to. If you are using the UForge Online SaaS platform, users will have access to all the formats. In certain circumstances, you may wish to restrict the formats shown to the user. You can either grey out a format or remove it altogether.

To grey out a format, find the <t:format> section of the format you want to be greyed out. This format will remain visible, but will not be available to the users. Set enabled to false:

<t:publish>
    <t:enabled>false<t:enabled>
<t:publish>

If you want to remove a format completely, then you can either comment it out (which will make it easier to integrate at a later time if needed), or you can simply remove the complete section, from <t:target> to </t:target>

Restricting the Cloud Accounts¶

When using the UForge Portal, all the cloud account types are displayed. You can restrict the cloud accounts visible using the config.xml file. You can either comment out a cloud account type or remove it altogether. In both cases, the cloud account format will no longer be visible.

To remove the complete section, delete from <t:account> to </t:account>

Customizing the CSS¶

You can customize all the CSS elements of Portal. You can modify a number of elements like text color, background color, font type and size using the custo.css file located in: /var/opt/UShareSoft/uforge-client/gwt/uforge/templates/css.

Customizing the Platform¶

You can customize some elements of your UForge Portal using the config.xml file located in: /etc/UShareSoft/uforge/uforge.conf. This is a relative path.

# /opt/UShareSoft/uforge-client/bin/uforge_ui_update.sh

# /opt/UShareSoft/uforge-client/bin/uforge_ui_update.sh

# /opt/UShareSoft/uforge-client/bin/uforge_ui_update.sh

# /opt/UShareSoft/uforge-client/bin/uforge_ui_update.sh

Troubleshooting¶

If you have errors with your Portal once you have applied the changes, please do the following:

1. Check the syntax of the customization files.
2. Check var/log/tomcat/catalina-daemon.out for error reports.