Siempre es un buen momento para repasar lo básico, con esto en mente, voy a comentar algunas de las cosas que puedes hacer con el interfaz de línea de comandos, Command Line Interface, de Payara Server.

See here for the original version in English language. 

 

La interfaz de linea de comandos, ó CLI, es un medio de controlar Payara Server desde la línea de comandos, o terminal si lo prefieres, permitiéndote iniciar, detener o modificar el servidor de muchas maneras. Mientras que para algunos la consola de administración es la opción preferida para ejecutar tareas de administración, el CLI puede ser una forma potencialmente más rápida y sencilla de realizar cualquier tarea de administración, particularmente cuando se trata con servidores “headless” (servidores sin interfaz gráfica).

 

Asadmin

El CLI de Payara Server se utiliza con la utilidad asadmin. Se puede encontrar en el directorio bin de tu instalación de Payara Server. Todos los comandos de administración de Payara Server son subcomandos de esta utilidad, y como tales, cada comando debe estar precedido con esta función (por ejemplo, ./asadmin hacer-alguna-acción).

 

Una pequeña sugerencia para evitar anteponer asadmin a cada comando es llamar a la función asadmin en sí misma (por ejemplo ./asadmin). Esto ejecutará la utilidad en modo interactivo, ahorrándote algo de tiempo si tienes la intención de ejecutar multiples comandos seguidos.

 

Puedes especificar opciones adicionales para la mayoría de comandos en el CLI, algunas de las cuales son obligatorios para ejecutar determinados comandos. La lista de opciones que un comando tiene, así como una descripción del comando y ejemplos, se puede encontrar pasando el parámetro –help al comando (por ejemplo, ./asadmin start-domain –help). Cada una de estas opciones debe ir precedida de “–“, aunque algunas opciones tienen una versión abreviada para la cual un sólo guión es suficiente.

 

Por ejemplo:

./asadmin start-domain –debug true

es equivalente a:

./asadmin start-domain -d

 

is equivalent to:

 

 ./asadmin start-domain –d

 

 

Iniciando y deteniendo …

Dominios

Como probablemente sabrás si ya tienes instalado Payara Server, Puedes utilizar el CLI para iniciar y detener dominios, clusters e instancias; es probable que la primera cosa que hicieras después de instalar Payara Server sea utilizar el CLI para iniciar el domino incluido por defecto:

./asadmin start-domain

 

El comando start-domain iniciará domain1 por defecto. Para iniciar un dominio alternativo debes especificar dicho dominio con un parámetro adicional como este:

./asadmin start-domain myDomain

 

Como señalamos anteriormente, puedes utilizar –help para listar los parámetros disponibles que cada comando puede utilizar. Haciéndolo para el comando start-domain revela los siguientes parámetros: dry-run, domaindir, upgrade, debug, verbose y watchdog. De particular interés son las opciones debug y verbose, las cuales son muy útiles para depurar.

 

Detener un dominio es tan sencillo como iniciarlo, simplemente es el comando stop-domain.

./asadmin stop-domain

Así como cuando se inician los dominios, domain1 es detenido por defecto. Para detener un dominio alternativo se debe especificar el dominio de forma explícita:

./asadmin stop-domain myDomain

 

Opciones destacables para este comando son force y kill. Estas opciones son útiles para especificar el comportamiento en el apagado de un dominio. La opción force determina si el dominio se detiene inmediatamente (true), o espera a que todos los hilos terminen antes de detener el dominio (false). La opción kill determina como termina el proceso del dominio. Su valor por defecto es false, lo que quiere decir que la plataforma Java terminará el proceso; especificar esta opción a true provocará que el sistema operativo elimine el proceso del dominio.

./asadmin stop-domain –kill true domain1

 

Instancias

Hay dos comandos para iniciar instancias de Payara Server: start-instance y start-local-instance. La mayor diferencia entre ellos es que el comando start-local-instance está diseñado solamente para iniciar instancias residentes en la máquina desde la que el comando se está ejecutando; start-instance puede utilizarse para iniciar tanto instancias locales como remotas.

 

./asadmin start-instance instance1

./asadmin start-local-instance instance2

 

Depurar está disponible para estos comandos con la opción –debug, la cual inicia una instancia con la depuración habilitada. Una opción adicional de depuración está disponible para el comando start-local-instance: –verbose. Te permite tener tanto los mensajes de arranque y de log impresos en la consola cuando se arranca una instancia, ayudándote a ver rápidamente que está ocurriendo.

 

Otra opción destacable y útil es –sync. Esta opción puede tomar uno de estos tres valores: none, normal y full. Si utilizas esta opción, debes especificar uno de estos valores; es obligatorio. La opción sync especifica como se sincronizan la instancias con el DAS (Servidor de Administrador de Dominios):

• El valor none significa que la instancia no se sincronizará con el DAS, por lo que no reflejará ningún cambio realizado desde la última sincronización. Esto puede ser útil si sabes que no ha habido cambios realizados, y quieres que la instancia arranque lo antes posible.
• normal mantiene la instancia sincronizada con cualquier cambio desde la última sincronización (que típicamente es la última vez que estuvo conectada). si no especificas la opción –sync, está será la opción por defecto de los comandos start-instance y start-local-instance. Este valor provoca que la instancia sincronice el directorio config, los subdirectorios modificados en las aplicaciones y el directorio docroot. Sin embargo, hay una excepción en la sincronización de subdirectorios: sólo los subdirectorios que han tenido un cambio en su nivel superior serán sincronizados; si un cambio se lleva a cabo más abajo en la jerarquía del sistema de archivos, pero no en el nivel superior, dichos cambios no serán sincronizados.
• La última opción, full, no está sujeto a la advertencia anterior. Este valor sincronizará todos los ficheros, incluso si estos no han sido alterados. Es la manera más completa de asegurar que una instancia está correctamente sincronizada, pero tiene sus inconvenientes: es más lento que las opciones normal y none, y requiere que el DAS se esté ejecutando; el comando de inicio de la instancia fallará y la instancia no será capaz de iniciar hasta que se contacte con el DAS de nuevo.

./asadmin start-local-instance –sync full –verbose true –debug true instance1

 

Así como con los comandos de detención para un dominio, los comandos para detener una instancia esta correctamente nombrados: stop-instance y stop-local-instance.La diferencia entre estos dos comandos es la misma que existe entre los comandos de inicio; el primero puede ser utilizado para instancias locales y remotas, mientras que el segundo solo se puede utilizar para instancias locales.

 

./asadmin stop-instance instance1

./asadmin stop-local-instance instance2

 

Igual que con el comando stop-domain, puedes especificar las opciones force y kill, las cuales actuan de la misma manera que lo hacen con el comando stop-domain.

 

 

Clusters

El comando para iniciar un cluster es start-cluster. Este comando arrancará todas las instancias del cluster. Si alguna de las instancias en el cluster ya se está ejecutando, este comando iniciará las que no lo estén únicamente.

 

./asadmin start-cluster cluster1

 

Este comando no tiene muchas opciones, sólo una que probablemente veas un uso común: la opción –verbose. Esta opción actúa como esperas, imprimiendo información relativa al arranque de cada instancia del cluster en la consola.

Para detener un cluster, utiliza el comando stop-cluster:

 

./asadmin stop-cluster cluster1

 

Este comando tiene la opción verbose, que mostrará mensajes del progreso de apagado de las instancias. También puedes especificar el comportamiento de apagado del cluster sea matando el proceso con la opción kill. Sin embargo, a diferencia de los comandos stop-domain, stop-instance y stop-local-instance, este comando no tiene la opción para forzar el apagado de sus instancias.

 

Creando …

Dominios

Ahora la cosa puede ponerse un poco complicada. Si sólo quieres crear un nuevo dominio con los valores por defecto, ejecuta el siguiente comando:

./asadmin create-domain

 

El cual te preguntará por un nombre específico para el dominio, un nombre de usuario y contraseña para el administrador. Entonces listará los puertos que usará como puertos por defecto, y generará un certificado auto-firmado.

Si quieres personalizar el dominio, entonces hay gran cantidad de opciones disponibles. A continuación algunas opciones relevantes:

• adminport: Esta opción especificará el puerto de administración que se utilizará (por defecto 4848).Instanceport: Esta opción especifica que puerto se utlizará para el contexto raíz de las aplicaciones web (por defecto 8080)portbase: Esta opción se utiliza para determinar las asignaciones de puertos, y no se puede utilizar con adminport, instanceport o domainproperties. El valor especificado para esta opción será el valor base, sobre el que otros puertos requeridos (por ejemplo el puerto de administración) serán calculados con un desplazamiento específico. Si el puerto base especificado fuera el 500, el puerto de administración sería 548 (500 más el desplazamiento del puerto de administración el cual es 48). El desplazamiento de cada puerto se puede ver en la ayuda del comando create-domain.
• template: Útil si ya tienes una plantilla de dominio que quieres copiar de una máquina a otra, esta opción permite especificar una plantilla que se utilizará para crear el nuevo dominio.
• usemasterpassword: Para mayor seguridad, puedes proteger el almacén de claves de Payara Server con una contraseña. Si no se especifica, entonces la contraseña changeit será utilizada; que es un valor por defecto bastante conocido, por lo cual se recomienda que sea cambiado al momento de asegurar y proteger la instalación de Payara Server.
• domainproperties: Esta opción te permite especificar cada puerto que se va a utilizar individualmente, en lugar de utilizar la opción portbase. Sin embargo vale la pena señalar que las opciones adminport e instanceport invalidarán los puertos de instancia y administración especificados en este comando. La lista completa de puertos que se pueden establecer está disponible en la ayuda del comando, aunque voy a enumerar algunos aquí: adminPort, domain.instancePort, http.ssl.port, java.debugger.port. Cuando especifiques múltiples valores, sepáralos con dos puntos(‘:’), por ejemplo  domain.adminPort=3456:domain.instanceport=4567

 

 

Nodos

Existen comandos para crear cada tipo de nodo de Payara Server: create-node-config, create-node-dcom, y create-node-ssh. Si estás creando un nodo CONFIG con los valores por defecto, sólo necesitas proporcionar el nombre del nodo. Si estás creando un nodo SSH o DCOM, tendrás que proporcionar tanto el nombre del nodo como el nombre de la máquina en la que el nodo se va a alojar.

 

./asadmin create-node-config configNode

./asadmin create-node-dcom –nodehost example.domain.co.uk dcomNode

./asadmin create-node-ssh –nodehost localhost sshNode

 

Si los valores por defecto cuando se está creando un nodo no son los adecuados, puedes especificar el nodo, directorio de instalación y directorio del nodo con las opciones nodehost, installdir y nodedir respectivamente.

./asadmin create-node-config –nodehost localhost –installdir /home/user/payara –nodedir /home/user/nodes configNode

 

Estas opciones se refieren a la máquina que alojará el nodo, el directorio de instalación de Payara Server de esa máquina y el directorio bajo el cual los nodos son almacenados (esta opción en particular probablemente se puede omitir en la mayoría de las situaciones). El directorio por defecto se toma de la ubicación de la instalación del DAS; las configuraciones por defecto asumen que Payara Server está instalado en la misma ubicación en todas las máquinas.

 

Debido a la relativa complejidad de un nodo SSH o DCOM en comparación de un nodo CONFIG, estos poseen más opciones que pueden ser usadas para crear y configurarlos respectivamente. La lista completa de opciones se puede ver pasando la opción help (./asadmin create-node-ssh –help), pero voy a mostrar algunas a continuación.

Para nodos SSH:

• force : Forzará la creación del nodo en la configuración del DAS, incluso si los parámetros facilitados para la creación del nodo fallan la validación. Esto puede ser útil si sabes que el nodo no podrá ser validado, ya que el nodo de referencia no está disponible en este momento. Esta opción también está disponible para el comando create-node-dcom.
• sshport : Si estás utilizando un puerto SSH distinto al puerto por defecto (22), utiliza esta opción para especificar que puerto se debe utilizar.
• sshuser : Especifica el usuario a utilizar cuando se conecta a la máquina a traves de SSH, que por defecto es el usuario del sistema operativo que está ejecutando el DAS.

Para nodos DCOM:

• windowsuser :Establece que usuario de Windows se va a utilizar a para conectar mediante DCOM. Si no se establece, por defecto utilizará el usuario que está ejecutando el proceso del DAS.
• windowsdomain :Especifica el dominio bajo el que el usuario de Winows se encontrará. En caso de omitirse, se asigna por defecto el anfitrión en el cual el comando es ejecutado.
• install :Esta opción especifica si se realizará la instalación de Payara Server en la máquina del nodo especificado. Esta opción también está disponible para el comando create-node-ssh

Clusters

Un cluster es creado por si solo mediante el CLI; cada instancia tiene que crearse y añadirse a un cluster por separado ( ver la siguiente sección). Para crear un cluster con los valores por defecto, escribir el comando create-cluster con un nombre para el cluster:

 

./asadmin create-cluster cluster1

 

Hay muchas maneras de poder configurar un cluster cuando se crea, aunque algunas de estas son opciones de compatibilidad, y no se deberían utilizar. Posiblemente la opción más comúnmente utilizada y la más útil sea –systemproperties. Esta opción es similar a la opción domainproperties del comando create-domain, ya que se utiliza para especificar individualmente cada puerto utilizado por las instancias del cluste. Cuando especificas múltiples puertos, separa los diferentes puertos con dos puntos (‘:’), así:

./asadmin create-cluster –systemproperties

ASADMIN_LISTENER_PORT=666:JAVA_DEBUGGER_PORT=777 cluster1

 

Instancias

Para crear instancias, existen dos comandos para ello: create-instance y create-lcoal-instance. Como verás por el nombre, el comando create-local-instance sólo puede ejecutarse en la máquina en la que la instancia residirá; no se puede utilizar para crear instancias en máquinas remotas. Este comando se utiliza para crear todo tipo de instancias. compartidas, independientes o en cluster.

 

./asadmin create-instance instance1

./asadmin create-local-instance instance2

 

El tipo de instancia creada se determina por los parámetros utilizados en su creación: una instancia compartida se crea especificando una configuración de instancia con la opción –config; una instancia en cluster se crea especificando un cluster al que la instancia pertenecerá con la opción –cluster.

 

./asadmin create-instance –config instance-config-1 instance3

./asadmin create-instance –cluster cluster12 instance4

 

Al igual que en la creación de un cluster, puedes especificar los puertos en los que la instancia escuchará con la opción –systemproperties.

Para especificar el nodo al que una instancia pertenecerá, utiliza la opción –node, así:

./asadmin create-instance –node node1

 

 

Estableciendo y cambiando contraseñas

Puedes utilizar el CLI para gestionar las contraseñas maestra y de administrador de Payara Server. Las dos contraseñas se gestionan con los siguientes comandos:

 

./asadmin change-admin-password

./asadmin change-master-password

 

El comando change-admin-password es específico de un dominio, por lo que las siguientes dos opciones te permiten especificar que dominio utilizar: domain_name y domaindir. Si existen multiples usuarios administradores, puedes especificar para que usuario cambiar la contraseña de esta manera:

 

./asadmin –user admin change-admin-password

 

El comando change-master-password tiene las siguientes opciones: nodedir, que especifica el directorio que contiene el nodo para el cual se va a cambiar la contraseña; domaindir, que especifica el directorio del dominio a utilizar; y savemasterpassword, que indica si la contraseña maestra se guardará o no en el disco (lo que es una mala práctica y no es recomendada, para que lo tengas en cuenta).

 

Desplegando una aplicación

Desplegar una aplicación puede ser una tarea bastante complicada dependiendo de la configuración de tu entorno. Por otro lado, desplegar una aplicación mediante el CLI puede ser significativamente más rápido que desplegarla desde la consola de administración si sabes lo que estás haciendo!

 

Para desplegar una aplicación en la instancia por defecto (el servidor donde la consola de administración está instalada), simplemente escribe lo siguiente:

 

./asadmin deploy <RUTA_COMPLETA_WAR_O_EAR>

 

Una vez tu entorno de Payara Server se encuentre configurado, no desplegarás a la instancia por defecto del servidor, por lo que la opción target te será de utilidad, ya que especifica donde se desplegará tu aplicación. Con esta opción puedes especificar que el componente se despliege en una instancia independiente, en un cluster o en un dominio.

 

./asadmin deploy –target cluster1 testWar

./asadmin deploy –target instance1 testWar

 

 

Concluyendo

Esto es todo para esta introducción al CLI de Payara Server. Has dado tus primeros pasos navegando en el desierto técnico que es el CLI, aunque el camino todavía se extiende bastante (durante el tiempo que estoy estirando esta metáfora). Espero que tu tu también veas que el CLI puede ser una alternativa viable a utilizar la consola de administración para administrar Payara Server, en lugar de algo innecesariamente complejo utilizado por la gente para presumir!

 

See here for the original version in English language.