======================== Documentação do CSGrid ======================== Visão Geral =========== CSGrid é um sistema para grades computacionais que, além de dar suporte ao uso e gerenciamento de recursos computacionais distribuídos, oferece facilidades para a integração de aplicações e para o gerenciamento de dados e usuários. O CSGrid apresenta para seu usuário uma área de trabalho com todas as aplicações disponíveis e com os arquivos de dados do usuário organizados por projeto. Um usuário pode estender o ambiente adicionando novas aplicações. O sistema também oferece uma série de recursos para trabalho colaborativo entre seus usuários. Arquitetura ----------- O CSGrid é composto dos seguintes componentes: Servidor Armazena as configurações dos usuários, seus projetos e dados, e também contém um repositório de algoritmos disponíveis para execução. A gerência de usuários, projetos, algoritmos e comandos é feita por meio das APIs RMI e REST. A primeira oferece permite a gerência completa e a segunda, mais limitada, apenas a gerência de projetos e comandos. Também oferece uma API REST para a comunicação com o SGA, que tipicamente não é acessada diretamente. SGA Componente responsável pela interação com os ambientes de execução. É ele que executa e monitorar a execução dos comandos e também coleta informações de utilização dos ambientes de execução. Pode-se ter mais de um SGA associado a um mesmo servidor CSGrid para que comandos sejam executados em recursos computacionais de vão desde simples computadores até grades computacionais. Cliente Desktop Interface gráfica para gerenciar usuários, projetos, algoritmos e comandos. Utiliza a tecnologia Java Web Start para fazer a instalação local. A seguir segue diagrama da arquitetura do CSGrid: .. image:: arquitetura.svg Guia de Instalação ================== Aqui são descritos os requisitos, os passos de instalação e como configurar o servidor CSGrid Requisitos ---------- Para a execução do servidor CSGrid as seguintes dependências devem estar instaladas na máquina: + Java 8 (Oracle ou OpenJDK) + Korn shell (ksh) + Docker (opcional) .. important:: As instruções para instalação/configuração/execução via Docker estão na sessão `Execução via Docker`_. Instalação ---------- Baixar do repositório o arquivo ``.tgz`` correspondente à versão a ser instalada, por exemplo usando o comando ``wget``: .. code-block:: console $ wget -c http://maven.tecgraf.puc-rio.br:8081/nexus/service/local/repositories/releases/content/br/puc-rio/tecgraf/csgrid/csgrid-full-package/X.Y.X/csgrid-full-package-X.Y.X-csgrid.tgz Substituindo ``X.Y.X`` pelo número da versão desejada. .. attention:: Pode ser necessário definir as variáveis de ambiente ``http_proxy`` e ``https_proxy`` para configurar o use de proxies ao comando ``wget``. Mais informações em `GNU Wget Manual:8.1 Proxies `_ Extrair o conteúdo do arquivo usando o comando ``tar``: .. code-block:: console $ tar -xzf csgrid-full-package-X.Y.Z-csgrid.tgz Se a extração foi feita com sucesso, o conteúdo do arquivo estará no diretório ``csgrid`` e deve conter os seguintes sub-diretórios: .. code-block:: console csgrid ├── algorithms ├── applications_repository ├── bin ├── config ├── html ├── lib ├── plugins ├── projects ├── properties └── security Aqui segue uma breve descrição de cada diretório: algorithms repositório de algoritmos applications_repository repositório de aplicações bin diretório com os scripts para inciar/para o servidor config diretório com os arquivos de configuração html diretório de documentação dos algoritmos lib diretório com as bibliotecas (.jar) usadas no servidor plugins repositório de plugins do servidor projects área de projetos (repositório de dados dos usuários) properties diretório com os arquivos padrões de configuração security diretório de armazenamento de chaves privadas do servidor Por fim instalar o Tomcat e a aplicação ``.war``: .. code-block:: console $ cd csgrid $ wget -c https://archive.apache.org/dist/tomcat/tomcat-6/v6.0.53/bin/apache-tomcat-6.0.53.tar.gz $ tar zxvf apache-tomcat-6.0.53.tar.gz $ ln -s apache-tomcat-6.0.53 tomcat $ unzip lib/tomcat/csgrid-client-war-*.war -d tomcat/webapps/csgrid Configuração ^^^^^^^^^^^^ No pacote de instalação existe um arquivo ``config/System.properties`` que contem as propriedades mínimas que devem ser configuradas para o funcionamento do servidor CSGrid. Abaixo segue o seu conteúdo: .. code-block:: properties # Server Name Server.name = CSGrid # Server hostname Server.hostName = # Server IP address Server.hostAddr = # Server URL Server.systemURL = http://:8080/csgrid/ # Webapp URL HttpService.webapp = http://:8080/csgrid/ # Mail server MailService.mail.smtp.host = # Mail server port MailService.mail.smtp.port = 25 # Server email address MailService.from = # Helpdesk email address MailService.support = # Local authentication plugin LoginService.login.plugin.protocol.1 = local LoginService.login.plugin.properties.1 = properties/LocalLogin.properties Como pode ser observado é necessário definir algumas propriedades. A seguir um exemplo de configuração do arquivo ``config/System.properties``: .. code-block:: properties # Server Name Server.name = CSGrid Xingu # Server hostname Server.hostName = xingu.amazonas.com.br # Server IP address Server.hostAddr = 10.0.0.1 # Server URL Server.systemURL = http://xingu.amazonas:8080/csgrid/ # Webapp URL HttpService.webapp = http://xingu.amazonas:8080/csgrid/ # Mail server MailService.mail.smtp.host = smtp.amazonas.com.br # Mail server port MailService.mail.smtp.port = 25 # Server email address MailService.from = csgrid@amazonas # Helpdesk email address MailService.support = suporte@amazonas # Local authentication plugin LoginService.login.plugin.protocol.1 = local LoginService.login.plugin.properties.1 = properties/LocalLogin.properties Configuração da localização de repositórios """"""""""""""""""""""""""""""""""""""""""" As localizações dos repositórios de algoritmo, aplicações, projetos e plugins estão configuradas para sub-diretórios do diretório raiz. Para alterá-las basta adicionar as seguinte propriedades no arquivo ``config/System.properties``: .. code-block:: properties # Deve ser o caminho absoluto ou relativo ao diretório raiz do CSGrid # Caminho para o diretório base de algoritmos AlgorithmService.base.algorithm.dir = ../../algorithms # Lista de diretórios para procurar aplicações ApplicationService.applications.directory.1 = applications_repository/applications ApplicationService.applications.directory.2 = /global/applications_repository/applications ApplicationService.categories.directory = applications_repository/categories PluginService.base.plugin.dir = plugins # Caminho para o diretório base de projetos ProjectService.base.project.dir = /storage/projects Tipicamente somente é alterada a localização do repositório de projetos, pois, como nele são guardados os dados dos usuários, este tende a crescer e acaba ocupando todo o disco local do servidor. Então para minimizar este problema pode-se armazenar a área de projetos em um storage externo. Outra vantagem de usar um storage externo é que os SGAs também podem ter acesso direto a área de projetos, facilitando suas configurações. Configurações da API REST """"""""""""""""""""""""" O CSGrid, além de oferecer uma API Java RMI usada pelo cliente desktop, também oferece uma API REST que pode ser usada por aplicações Web ou por outras aplicações com capacidade de fazer requisições HTTP. Para ativá-la é necessário definir algumas propriedades, que podem ser vistas no exemplo abaixo: .. code-block:: properties # Indica se o serviço está habilitado. Os valores podem ser true ou false. RestService.enabled = true # Porta onde o container exporta as APIs dos serviços RestService.service.port = 8010 # URL pela qual a API REST deve ser acessada RestService.external.url = http:///xingu.amazonas:8010/v1 # Chave privada usada para geração de token de acesso a API RestService.private.key.file = security/xingu.key # Configuração opcional do SSL RestService.SSL.enable = true # KeyStore no formato JKS para armazenar a chave privada e o certificado associado RestService.SSL.keystore = security/xingu.jks # A senha do KeyStore RestService.SSL.keystore_password = csgrid Abaixo segue os comandos de criação da chave ``security/xingu.key`` usada no exemplo anterior: .. code-block:: console $ cd security $ openssl genrsa -out rsa.key 2048 $ openssl pkcs8 -topk8 -nocrypt -in rsa.key -out xingu.key -outform DER Configuração da API REST SGA """""""""""""""""""""""""""" A API REST SGA é oferecida pelo plugin ``csbase-sga-rest`` do CSBase, então para ativá-la é necessário que ele seja ativado e configurado. Para isto adicione as seguinte linhas ao arquivo ``config/System.properties``: .. code-block:: properties SGAService.sga.plugin.type.1 = rest SGAService.sga.plugin.properties.1 = plugins/sgarest.properties E crie o arquivo ``plugins/sgarest.properties`` com o seguinte conteúdo alterando as propriedades ``host`` e ``port``: .. code-block:: properties # Nome do SGA (necessário por compatibilidade) csbase_sga_name = SGA_REST csbase_name = SGA_REST # Host e porta de acesso a API host = 10.0.0.1 port = 40509 .. important:: As instruções de instalação e configuração do SGA-REST estão disponíveis em https://sga-rest-daemon.readthedocs.io/. A instalação do SGA é necessária para permitir a execução de comandos no CSGrid. Configuração de autenticação via LDAP """"""""""""""""""""""""""""""""""""" O CSGrid permite delegar a autenticação de usuários para outros servidores/protocolos. Um dos protocolos suportados é o LDAP que é ativado pelo plugin ``csbase-login-ldap`` do CSBase. Para ativá-lo adicione as seguinte linhas ao arquivo ``config/System.properties``: .. code-block:: properties LoginService.login.plugin.protocol.2 = ldap LoginService.login.plugin.properties.2 = plugins/LDAPLogin.properties E crie o arquivo ``plugins/LDAPLogin.properties`` usando como base o exemplo abaixo: .. code-block:: properties # Servidores LDAP disponíveis para autenticação e suas portas. LDAPServer.1 = dc01 LDAPPort.1 = 389 # Lista de padrões para autenticação dos usuários. [%U] é substituído pelo # login do usuário. LDAPPattern.1 = [%U]@amazonas #LDAPPattern.2 = cn=[%U],ou=CSGrid,dc=xingu,dc=amazonas #LDAPPattern.2 = cn=[%U],dc=xingu,dc=amazonas # CharSet utilizado na conversão da senha em um byte[]. #LDAPCharSet = UTF8 LDAPCharSet = ISO-8859-1 # Timeout para conexão com o servidor LDAP, em segundos LDAPConnectionTimeout = 5 # Suporte a SSL LDAPSSLEnabled = false # Configuração do KeyStore para acesso usando SSL #LDAPKeyStorePath = security/ldap.jks #LDAPKeyStorePassword = csgrid Arquivos de log """"""""""""""" Os arquivos de log são gerados no diretório ``logs/server`` conforme a configuração padrão, e no arquivo ``properties/Logging.properties`` está e outras propriedades podem ser alteradas. Execução ======== Para iniciar o CSGrid execute o seguinte comando em um shell/terminal: .. code-block:: console $ cd bin $ ./csgrid start Para parar o seguinte comando deve ser executado: .. code-block:: console $ cd bin $ ./csgrid stop Execução via Docker ------------------- A imagem do CSGrid está no repositório ``repo.tecgraf.puc-rio.br:18089`` e no caminho ``soma/csgrid``, assim para pegar a versão ``x.y.z`` o seguinte comando deve ser usado: .. code-block:: console $ docker pull repo.tecgraf.puc-rio.br:18089/soma/csgrid:x.y.z Para a execução via Docker deve-se definir e mapear os seguintes volumes: /csgrid/projects Área de projetos /csgrid/algorithms Repositório de algoritmos /csgrid/persist Dados de persistência /csgrid/security Diretório de certificados/chaves /csgrid/logs Diretório de logs .. important:: A chave usada para configurar a API REST deve estar no diretório mapeado em ``/csgrid/security`` e deve ser nomeada ``rest_api_token_key``. Detalhes sobre a API REST em `Configurações da API REST`_ As seguintes variáveis de ambiente devem ser definidos no container: CSGRID_SERVER_NAME Nome do servidor CSGRID_HOST_NAME Nome da máquina do servidor CSGRID_RMI_REGISTRY_PORT Porta do registro RMI CSGRID_RMI_EXPORT_PORT Porta RMI exportada CSGRID_FTC_EXPORT_PORT Porta FTC exportada CSGRID_REST_EXPORT_PORT Portas da API REST do servidor exportada CSGRID_LDAP_AUTH Indicador opcional para ativar a autenticação via LDAP. A definição de qualquer valor basta para ativar a funcionalidade. Por exemplo: ``"CSGRID_LDAP_AUTH=1"`` .. important:: Para configurar a autenticação via LDAP veja a sessão `Configuração de autenticação via LDAP`_ e mapeie o arquivo de propriedades para o seguinte caminho no container: ``/csgrid/properties/LDAPLogin.properties``. Por exemplo: .. code-block:: bash $ docker run ... -v /external/LDAPLogin.properties:/csgrid/properties/LDAPLogin.properties:ro ... repo.tecgraf.puc-rio.br:18089/soma/csgrid:x.y.z As seguintes portas devem ser exportadas -- use o valor definido nas variáveis de ambiente acima para saber qual deve ser a porta exportada para alguns serviços: 8010 REST API - Porta para acessar a API REST do CSGrid 1099 Java RMI - Porta para acessar a API Java RMI do CSGrid (``CSGRID_RMI_REGISTRY_PORT``) 1098 Java RMI - Porta para acessar a API Java RMI do CSGrid (``CSGRID_RMI_EXPORT_PORT``) 6681 FTC - Porta para acesso ao serviço FTC -- transferência de arquivos -- do CSGrid (``CSGRID_FTC_EXPORT_PORT``) 8080 Java Web Start - Porta para acessar o servidor Tomcat para disparar a aplicação Java via Java Web Start 7778 SGA - Porta para acessar a API CORBA do SGA 7878 SGA-SSL - Porta para acessar a API CORBA do SGA usando SSL 40500 SGA-REST - Porta para acessar a API REST do SGA (``CSGRID_REST_EXPORT_PORT``) -- é a porta onde o SGA publica a sua API REST E por fim, utilizar as seguintes opções do comando ``docker run``: -\-network=host Usar a configuração de rede da máquina hospedeira -\-user user_id:group_id Executar informando o UID e GID do usuário que irá executar o processo do servidor -\-restart=unless-stopped Define a política de reinício do container Docker. O valor ``unless-stopped`` indica que o container deve ser reiniciado sempre, menos se ele foi parado antes do daemon Docker ter sido parado. Mais detalhes em `Docker run reference:Restart policies `_ Exemplo de script para iniciar um container Docker usando a imagem do CSGrid: .. code-block:: bash #!/bin/bash REPO=repo.tecgraf.puc-rio.br:18089 IMAGE=soma/csgrid VERSION=x.y.z WORKING_DIR=$(dirname "$PWD") CONTAINER_NAME=csgrid-${VERSION} function start() { docker run -d \ --rm \ --name ${CONTAINER_NAME} \ -p 8010:8010 \ -p 1099:1099 \ -p 1098:1098 \ -p 6681:6681 \ -p 8080:8080 \ -p 7778:7778 \ -p 7878:7878 \ -p 40500:40500 \ -v "${WORKING_DIR}/data/persist":/csgrid/persist \ -v "${WORKING_DIR}/data/projects":/csgrid/projects \ -v "${WORKING_DIR}/data/algorithms":/csgrid/algorithms \ -v "${WORKING_DIR}/data/security":/csgrid/security \ -v "${WORKING_DIR}/data/logs":/csgrid/logs \ -e "CSGRID_SERVER_NAME=CSGrid" \ -e "CSGRID_HOST_NAME=${HOSTNAME}" \ -e "CSGRID_RMI_REGISTRY_PORT=1099" \ -e "CSGRID_RMI_EXPORT_PORT=1098" \ -e "CSGRID_FTC_EXPORT_PORT=6681" \ -e "CSGRID_REST_EXPORT_PORT=8010" \ --restart=unless-stopped \ --network=host \ --user "$(id -u "${USER}")":"$(id -g "${USER}")" \ ${REPO}/${IMAGE}:${VERSION} } function stop() { docker stop ${CONTAINER_NAME} } case "$1" in start) start ;; stop) stop ;; *) echo "Usage: csgrid.sh {start|stop}" ;; esac .. important:: A imagem Docker do CSGrid define o ``umask`` para o valor ``002``, fazendo com que todos os usuários Unix do grupo informado no argumento ``--user`` do comando ``docker run`` tenham acesso de leitura e escrita aos arquivos e diretórios criados pelo container. Importante enfatizar que isso é válido também para aqueles localizados nos volumes mapeados. Execução em ambiente com escalonadores de jobs em clusters ---------------------------------------------------------- O CSGrid pode usar escalonadores de jobs em clusters para execução de comandos e assim aproveitar todos os benefícios que esses sistemas oferecem. Um desses benefícios é a definição de uma política de alocação de recursos com base no usuário de submissão do job. Um exemplo de política seria uma que defina que um usuário pode executar em máquinas com alta capacidade de CPU ou de GPU. Ou ainda uma que defina que um outro usuário somente tem permissão de executar em um número reduzido de nós do cluster. Para tanto é necessário uma atenção especial na configuração do SGA -- mais detalhes em https://sga-rest-daemon.readthedocs.io/ -- e na definição de um grupo de usuários para aproveitar os sinalizadores de direitos de acesso do Unix. .. important:: Essa configuração somente é recomendada para os casos em que seja realmente necessário que os jobs sejam submetidos ao escalonador do cluster em nome do usuário final. Se a submissão de jobs puder ser feita pelo usuário do sistema -- assumindo que é esse usuário que executa tanto o servidor CSGrid quanto o SGA -- os jobs em execução no cluster já terão acesso de leitura e escrita aos arquivos e diretórios da área de projetos. Um configuração recomendada é a adição do usuário do sistema -- aquele que executa o servidor CSGrid e o SGA -- e dos usuários finais -- correspondentes daqueles que utilizarão o CSGrid -- a um novo grupo de usuários Unix criado exclusivo para a utilização do CSGrid. Dessa forma os arquivos armazenados na área de projetos serão acessíveis pelos jobs submetidos em nome de um usuário final ao escalonador do cluster. .. attention:: É necessário que o ``umask`` do usuário do sistema -- que executa o servidor CSGrid e o SGA -- seja ``002``, para que os sinalizadores de direitos de acesso Unix padrões para grupo permitam a leitura e escrita nos arquivos e diretórios criados pelo servidor CSGrid. O comando ``umask 002`` pode ser adicionado ao script de inicialização do CSGrid e do SGA -- no caso da execução via Docker esse já é o comportamento padrão. .. attention:: É necessário ativar o ``setgid`` nos diretórios raiz da área de projetos, raiz do repositório de algoritmos e no de armazenamento de dados do SGA -- definido pela chave ``runtime_data_dir``. Segue exemplo do comando: .. code-block:: bash $ chmod g+s path_to_projects_root_dir $ chmod g+s path_to_algorithms_root_dir $ chmod g+s path_to_runtime_data_dir Desta forma quaisquer diretórios e arquivos criados dentro da área de projetos, do repositório de algoritmos ou do diretório de armazenamento de dados do SGA herdarão o grupo destes, permitindo que eles sejam acessíveis com permissão de leitura e escrita pelo servidor CSGrid. .. TODO Adicionar sessão com instruções para verificação da instalação Verificando a instalação ------------------------ Execução do Cliente Desktop --------------------------- Para executar o Cliente Desktop execute o comando, substituindo na URL o ``host`` e ``port`` conforme a configuração do ambiente: .. code-block:: bash $ javaws http://host:port/csgrid/init