From 5f04f1555cfd9fe140b7ffd8b3852e86c1ca6b73 Mon Sep 17 00:00:00 2001 From: Jeff Ohrstrom Date: Thu, 30 Nov 2023 14:53:25 -0500 Subject: [PATCH] add reference material for submit.yml.erb back (#891) Add reference material for submit.yml.erb back. --- .../app-development/interactive/form.rst | 13 + .../interactive/global-submit.inc | 18 + .../app-development/interactive/submit.rst | 47 +- source/reference.rst | 1 + source/reference/files/submit-yml-erb.rst | 36 ++ .../files/submit-yml/basic-bc-options.rst | 386 +++++++++++++++ source/reference/files/submit-yml/script.rst | 457 ++++++++++++++++++ .../files/submit-yml/vnc-bc-options.rst | 226 +++++++++ 8 files changed, 1153 insertions(+), 31 deletions(-) create mode 100644 source/how-tos/app-development/interactive/global-submit.inc create mode 100644 source/reference/files/submit-yml-erb.rst create mode 100644 source/reference/files/submit-yml/basic-bc-options.rst create mode 100644 source/reference/files/submit-yml/script.rst create mode 100644 source/reference/files/submit-yml/vnc-bc-options.rst diff --git a/source/how-tos/app-development/interactive/form.rst b/source/how-tos/app-development/interactive/form.rst index cf1e7726e..8c35466b2 100644 --- a/source/how-tos/app-development/interactive/form.rst +++ b/source/how-tos/app-development/interactive/form.rst @@ -132,18 +132,24 @@ part of the app developer can look like: The most commonly used predefined attributes are given as: +.. _bc_account: + bc_account This adds a ``text_field`` to the HTML form that will be used as the charged account for the submitted job. This attribute gets directly set on `OodCore::Job::Script#accounting_id`_. +.. _bc_queue: + bc_queue This adds a ``text_field`` to the HTML form that will supply the name of the queue that the batch job is submitted to. This attribute gets directly set on `OodCore::Job::Script#queue_name`_. +.. _bc_num_hours: + bc_num_hours This adds a ``number_field`` to the HTML form that describes the maximum amount of hours the submitted batch job may run. @@ -167,6 +173,8 @@ bc_num_slots :ref:`interactive-development-form-customizing-attributes`) to work at your center. +.. _bc_email_on_started: + bc_email_on_started This adds a ``check_box`` to the HTML form that determines whether the user should be notified by email when the batch job starts. @@ -223,12 +231,15 @@ auto_modules_ referenced in the ``script.sh.erb`` as ``<%= auto_modules_netcdf_serial %>`` replacing any hyphens (``-``) with underscores ``_``. +.. _auto_groups: auto_groups This will automatically generate a ``select`` widget populated with a list of the Unix groups the user is currently in. Administrators can configure :ref:`filter for autogroups ` to limit the groups shown. +.. _auto_queues: + auto_queues This will generate a ``select`` widget list of all the queues available to the user. These queues will be cluster if you have :ref:`dynamic options ` @@ -238,6 +249,8 @@ auto_queues .. warning:: We only have support for Slurm queues (partitions) at this time. +.. _auto_accounts: + auto_accounts This will generate a ``select`` widget list of all the accounts available to the user. diff --git a/source/how-tos/app-development/interactive/global-submit.inc b/source/how-tos/app-development/interactive/global-submit.inc new file mode 100644 index 000000000..4e99ebed7 --- /dev/null +++ b/source/how-tos/app-development/interactive/global-submit.inc @@ -0,0 +1,18 @@ +Setting Batch Connect Options Globally +-------------------------------------- + +All of these configuration items can also be applied globally to the entire cluster +in the cluster definition files under ``/etc/ood/config/clusters.d/``. If set globally, +the option is applied to all applications in that cluster. + +Here's an example of how to set the ``header`` configuration for both vnc and basic +templates. + + .. code-block:: yaml + + v2: + batch_connect: + basic: + header: "#!/bin/bash" + vnc: + header: "#!/bin/bash" \ No newline at end of file diff --git a/source/how-tos/app-development/interactive/submit.rst b/source/how-tos/app-development/interactive/submit.rst index 542853bac..e83d3e2a2 100644 --- a/source/how-tos/app-development/interactive/submit.rst +++ b/source/how-tos/app-development/interactive/submit.rst @@ -7,6 +7,12 @@ The configuration file ``submit.yml.erb`` controls the content of the batch script as well as the submission arguments used when submitting the batch job. It is located in the root of the application directory. +.. tip:: + This page is an introduction to the ``submit.yml.erb``, it's contents + and it's use. + + Reference documentation holds :ref:`all configuration items for submit.yml.erb `. + Assuming we already have a sandbox Interactive App deployed under:: ${HOME}/ondemand/dev/my_app @@ -28,8 +34,8 @@ The three possible configuration options that can be used in the .. describe:: batch_connect (Hash) - the configuration describing the batch script content (see - `OodCore::BatchConnect::Template`_ for valid configuration options) + The configuration describing the batch script content. + Reference documentation holds :ref:`all configuration items for submit.yml.erb `. Example Use the default basic web server template @@ -43,8 +49,9 @@ The three possible configuration options that can be used in the .. describe:: script (Hash) - the configuration describing the job submission parameters for the batch - script (see `OodCore::Job::Script`_ for valid configuration options) + The configuration describing the job submission parameters for the batch + script. Reference documentation holds + :ref:`all configuration items for submit.yml.erb `. Example Set the job's charged account and queue @@ -112,22 +119,20 @@ All batch scripts are generated from either the ``basic`` template or the batch_connect: template: "vnc" -Aside from the above configuration option, a list of all possible configuration -options for ``batch_connect`` can be found under the code documentation for -`OodCore::BatchConnect::Template`_. +Reference documentation holds :ref:`all configuration items for submit.yml.erb `. .. note:: The configuration ``template: "vnc"`` comes with more ``batch_connect`` configuration options which can be found under the code documentation for - `OodCore::BatchConnect::Templates::VNC`_. + :ref:`vnc-bc-options`. Configure Script ```````````````` The ``script`` configuration option defines the batch job submission parameters (e.g., number of nodes, wall time, queue, ...). The list of all possible -options can be found under the code documentation for `OodCore::Job::Script`_. +options can be found under the code documentation for :ref:`submit-script-options`. It is recommended to refrain from using the ``native`` option to best keep your Interactive App as portable as possible. Although we understand this may not be @@ -221,7 +226,7 @@ script it forks off into the background. This can be configured with: Specify Job Submission Parameters ````````````````````````````````` -Cherry-picking some possible options from `OodCore::Job::Script`_ gives a batch +Cherry-picking some possible options from :ref:`submit-script-options` gives a batch job built from the basic web server template submitted with the following parameters: @@ -299,27 +304,7 @@ the user supplied a non-blank value to the form attribute ``my_queue``. .. _global-bc-settings: -Setting Batch Connect Options Globally -`````````````````````````````````````` - -All of these configuration items can also be applied globally to the entire cluster -in the cluster definition files under ``/etc/ood/config/clusters.d/``. If set globally, -the option is applied to all applications in that cluster. - -Here's an example of how to set the ``header`` configuration for both vnc and basic -templates. - - .. code-block:: yaml - - v2: - batch_connect: - basic: - header: "#!/bin/bash" - vnc: - header: "#!/bin/bash" +.. include:: global-submit.inc .. _eruby (embedded ruby): https://en.wikipedia.org/wiki/ERuby -.. _`oodcore::batchconnect::template`: http://www.rubydoc.info/gems/ood_core/OodCore/BatchConnect/Template -.. _`oodcore::batchconnect::templates::vnc`: http://www.rubydoc.info/gems/ood_core/OodCore/BatchConnect/Templates/VNC -.. _`oodcore::job::script`: http://www.rubydoc.info/gems/ood_core/OodCore/Job/Script .. _ruby strings: https://ruby-doc.org/core-2.2.3/String.html diff --git a/source/reference.rst b/source/reference.rst index 78c856404..2941449f4 100644 --- a/source/reference.rst +++ b/source/reference.rst @@ -14,6 +14,7 @@ make up the Open OnDemand infrastructure. reference/files/ood-portal-yml reference/files/nginx-stage-yml reference/files/ondemand-d-ymls + reference/files/submit-yml-erb.rst .. toctree:: :maxdepth: 1 diff --git a/source/reference/files/submit-yml-erb.rst b/source/reference/files/submit-yml-erb.rst new file mode 100644 index 000000000..2ea531695 --- /dev/null +++ b/source/reference/files/submit-yml-erb.rst @@ -0,0 +1,36 @@ +.. _submit-yml-erb: + +submit.yml.erb +============== + +This is the file that is submitted to a batch connect job. It is comprised +of a ``script`` and a ``batch_connect`` attribute. The ``batch_connect`` +attribute can either be a ``basic`` template if your app is already an +http server or a ``vnc`` template if you need VNC capabilities. + +These are reference pages, you can see +:ref:`app-development-interactive-submit` for a broader overview. + +.. toctree:: + :maxdepth: 2 + + submit-yml/basic-bc-options + submit-yml/vnc-bc-options + submit-yml/script + +Simple Example +-------------- + + .. code-block:: yaml + + # a simple script.yml.erb file + + script: + native: + - "-n" + - "1" + batch_connect: + template: "basic" + header: "#!/bin/bash" + +.. include:: ../../how-tos/app-development/interactive/global-submit.inc \ No newline at end of file diff --git a/source/reference/files/submit-yml/basic-bc-options.rst b/source/reference/files/submit-yml/basic-bc-options.rst new file mode 100644 index 000000000..e2b312519 --- /dev/null +++ b/source/reference/files/submit-yml/basic-bc-options.rst @@ -0,0 +1,386 @@ +.. _basic-bc-options: + +Basic Batch Connect Options +=========================== + + .. code-block:: yaml + + batch_connect: + template: "basic" + work_dir: nil + conn_file: "connection.yml" + conn_params: + - host + - port + - password + bash_helpers: "..." + min_port: 2000 + max_port: 65535 + password_size: 8 + header: "" + footer: "" + script_wrapper: "%s" + set_host: "host=$(hostname)" + before_script: "..." + before_file: "before.sh" + run_script: "..." + script_file: "./script.sh" + timeout: "" + clean_script: "..." + clean_file: "clean.sh" + +.. describe:: min_port (Integer, 2000) + + the smallest value to use when trying to open a port + + Default + 2000 is the lowest value to use when trying to open a port + + .. code-block:: yaml + + min_port: 2000 + + Example + set the lowest possible port number to 3005 + + .. code-block:: yaml + + min_port: 3005 + +.. describe:: max_port (Integer, 65535) + + the largest value to use when trying to open a port + + Default + 65535 is the highest possible value a port could have + + .. code-block:: yaml + + max_port: 65535 + + Example + set the highest possible port number to 40000 + + .. code-block:: yaml + + max_port: 40000 + +.. describe:: password_size (Integer, 8) + + the number of characters in the passwords + + Default + passwords will be generated with 8 characters + + .. code-block:: yaml + + password_size: 8 + + Example + passwords will be generated with 32 characters + + .. code-block:: yaml + + password_size: 32 + +.. describe:: header (String, "") + + the script header + + Default + the script has no header + + .. code-block:: yaml + + header: "" + + Example + set the header to a bash shebang + + .. code-block:: yaml + + header: "#!/bin/bash" + +.. describe:: footer (String, "") + + commands at the bottom of the script + + Default + the script has no footer + + .. code-block:: yaml + + header: "" + + Example + print the end time of the job + + .. code-block:: yaml + + header: 'echo "all done at $(date)"' + +.. describe:: script_wrapper (String, "%s") + + wrap the script ('%s' being the script content) with commands before + and after + + Default + the script has no wrapper + + .. code-block:: yaml + + script_wrapper: "%s" + + Example + load a module before the script and echo a statement after it + + .. code-block:: yaml + + script_wrapper: | + module load vnc + %s + echo "all done now!" + + +.. describe:: set_host (String, "host=$(hostname)") + + set the host variable with this command + + Default + the host variable is set by the hostname command + + .. code-block:: yaml + + set_host: "host=$(hostname)" + + Example + the host variable the first item in the ``hostname -A`` output + + .. code-block:: yaml + + set_host: "host=$(hostname -A | awk '{print $1}')" + +.. describe:: before_script (String, "...") + + commands to execute the before file + + Default + sources the configurable ``before_file`` if it exists + + .. code-block:: ruby + + def before_script + context.fetch(:before_script) do + before_file = context.fetch(:before_file, "before.sh").to_s + + "[[ -e \"#{before_file}\" ]] && source \"#{before_file}\"" + end.to_s + end + + Example + temporarily override the PATH variable when executing the before script + + .. code-block:: yaml + + before_script: | + # careful now, we can't override before_file or we have to + # change it here too! + PATH=$PATH:/opt/ood-before/bin source before.sh + +.. describe:: before_file (String, "before.sh") + + the script file to run before the main script + + Default + execute the file before.sh before the main script + + .. code-block:: yaml + + before_file: "before.sh" + + Example + execute the file prepare.sh before the main script + + .. code-block:: yaml + + before_file: "prepare.sh" + +.. describe:: run_script (String, "...") + + commands to execute the main file + + Default + execute the configurable ``script_file`` or optionally run with + the timeout command if there is a timeout given. + + .. code-block:: ruby + + def run_script + context.fetch(:run_script) do + script_file = context.fetch(:script_file, "./script.sh").to_s + timeout = context.fetch(:timeout, "").to_s + + timeout.empty? ? "\"#{script_file}\"" : "timeout #{timeout} \"#{script_file}\"" + end.to_s + end + + Example + execute the main script in a singularity container + + .. code-block:: yaml + + run_script: | + # careful now, we can't override run_file or we have to + # change it here too! This also doesn't account for timeout, + # if it's provided. + IMAGE=/opt/images/centos7.sif + singularity exec -p $IMAGE /bin/bash script.sh + +.. describe:: script_file (String, "./script.sh") + + the main script file + + Default + execute the file script.sh in the current working directory + + .. code-block:: yaml + + script_file: "./script.sh" + + Example + execute the file other_main.sh in the current working directory + + .. code-block:: yaml + + script_file: "./other_main.sh" + +.. describe:: timeout (String, "") + + timeout (in seconds) of the main script + + Default + no timeout applied to the main script file + + .. code-block:: yaml + + script_file: "" + + Example + all scripts timeout after 3600 seconds (1 hour) + + .. code-block:: yaml + + script_file: "3600" + +.. describe:: clean_script (String, "...") + + commands to execute the clean script file + + Default + sources the configurable ``clean_file`` if it exists + + .. code-block:: ruby + + def clean_script + context.fetch(:clean_script) do + clean_file = context.fetch(:clean_file, "clean.sh").to_s + + "[[ -e \"#{clean_file}\" ]] && source \"#{clean_file}\"" + end.to_s + end + + Example + temporarily override the PATH variable when executing the clean script + + .. code-block:: yaml + + clean_script: | + # careful now, we can't override clean_file or we have to + # change it here too! + PATH=$PATH:/opt/ood-clean/bin source clean.sh + +.. describe:: clean_file (String, "clean.sh") + + the cleanup script file + + Default + execute the file clean.sh + + .. code-block:: yaml + + clean_file: "clean.sh" + + Example + execute the file scrub.sh + + .. code-block:: yaml + + clean_file: "scrub.sh" + +.. describe:: conn_params (Array, ['host','port','password']) + + The connection parameters that will be written to the ``conn_file``. + This is useful when you need to generate something in one of the shell scripts + and pass it back to the ``view.html.erb`` through the ``connection.yml`` file. + + .. note:: + Anything added here will be *added to* the default. The default + configuration is required and so cannot be overridden, only added to. + + Default + 'host', 'port' and 'password' + + .. code-block:: yaml + + conn_params: [ 'host', 'port', 'password' ] + + Example + The API to connect to can change in the ``script.sh.erb`` based off of + something that can only be determined during the job (for example an + environment variable in a module). + + .. code-block:: yaml + + conn_params: + - the_connect_api + +.. warning:: + These items below should not be set by users. They are + given for completeness only. It's likely they'll cause + errors if overridden. + + +.. describe:: work_dir (String, null) + + the working directory of the job. This is set by the dashboard + for batch connect apps and users shouldn't need to set it. + + Default + set by the dashboard to a directory under ~/ondemand/data + + Example + no example given because users shouldn't set this value + +.. describe:: conn_file (String, "connection.yml") + + the file all the connection data will be written to + + Default + a file named 'connection.yml' + + .. code-block:: yaml + + conn_file: "connection.yml" + + Example + no example given because users shouldn't set this value + +.. describe:: bash_helpers (String, "...") + + a library of bash utility functions called in all the other scripts + + Default + a very large set of functions. See source code for complete library + + Example + no example given because users shouldn't set this value \ No newline at end of file diff --git a/source/reference/files/submit-yml/script.rst b/source/reference/files/submit-yml/script.rst new file mode 100644 index 000000000..64b2ad063 --- /dev/null +++ b/source/reference/files/submit-yml/script.rst @@ -0,0 +1,457 @@ +.. _submit-script-options: + +Batch Connect Script Options +============================ + +The ``script`` section of the :ref:`submit-yml-erb` file defines +the arguments you're passing to the scheduler when you submit the +script. + +.. warning:: + These options are documented here for completeness. Some may not + be available to override in batch connect applications. + + For example, ``workdir`` is set by the OnDemand system in batch + connect applications, and cannot be overidden. + +.. tip:: + If you're using the ``ood_core`` gem (where all these are defined and used) + you should refer to `ood_core gem Ruby docs`_. + +.. code-block:: yaml + + script: + content: nil + args: nil + submit_as_hold: nil + rerunnable: nil + job_environment: nil + workdir: nil + email: nil + email_on_started: nil + email_on_terminated: nil + job_name: nil + shell_path: nil + error_path: nil + input_path: nil + output_path: nil + reservation_id: nil + queue_name: nil + priority: nil + start_time: nil + wall_time: nil + accounting_id: nil + native: nil + copy_environment: nil + + +Note the use of ERB templates throughout these examples. + +.. describe:: content (String, nil) + + The content of the script being submitted. + + Default + Not set initially, but specified by OnDemand system automatically. + + .. code-block:: yaml + + content: "" + + Example + **None given because users cannot specify this in batch connect applications.** + +.. describe:: args (Array, nil) + + Extra arguments to pass to the schedulers' submit command. + + Default + Empty, no extra arguments. + + .. code-block:: yaml + + args: nil + + Example + Pass arguments ``--foo`` and ``--bar`` into the submit command. + + .. code-block:: yaml + + args: + - "--foo" + - "--bar" + +.. describe:: submit_as_hold (Boolean, nil) + + Hold the job after submitting. + + Default + Empty, do not hold the job. + + .. code-block:: yaml + + submit_as_hold: nil + + Example + Always hold the job. + + .. code-block:: yaml + + submit_as_hold: true + +.. describe:: rerunnable (Boolean, nil) + + Indicate whether the job is rerunnable. + + Default + Empty, it is not rerunnable. + + .. code-block:: yaml + + rerunnable: nil + + Example + The job is rerunnable. + + .. code-block:: yaml + + rerunnable: true + +.. describe:: job_environment (Hash, nil) + + Extra environment variables to pass into the schedulers' submit command. + + Default + Empty, no extra environment variables. + + .. code-block:: yaml + + job_environment: nil + + Example + Set the ``SINGULARTITY_BIND_PATH`` environment variable to ``/etc,/tmp,/home`` and + ``MY_APP_IMAGE`` to ``/opt/app.img``. + + .. code-block:: yaml + + job_environment: + SINGULARTITY_BIND_PATH: "/etc,/tmp/home" + MY_APP_IMG: "/opt/app.img" + +.. describe:: workdir (String, nil) + + The working directory of the job. + + Default + Not set initially, but specified by OnDemand system automatically. + + .. code-block:: yaml + + workdir: nil + + Example + **None given because users cannot specify this in batch connect applications.** + + +.. describe:: email (Array, nil) + + Addresses to send emails to when the job starts or stops. + + Default + Empty, uses the schedulers' default. + + .. code-block:: yaml + + email: nil + + Example + Use a specific email address. + + .. code-block:: yaml + + email: + - "<%= ENV['USER'] %>@the-real-domain-I-want.edu" + +.. describe:: email_on_started (Boolean, nil) + + Have the scheduler send an email when the job has started. + + Default + Not set, uses the schedulers' default. + + .. code-block:: yaml + + email_on_started: nil + + Example + **None given because users should use :ref:`bc_email_on_started` instead + of supplying it here**. + +.. describe:: email_on_terminated (Boolean, nil) + + Have the scheduler send an email when the job has finished. + + Default + Not set, uses the schedulers' default. + + .. code-block:: yaml + + email_on_terminated: nil + + Example + Given the form checkbox option ``email_on_terminated``, set this attribute. + + .. code-block:: yaml + + email_on_terminated: "<%= email_on_terminated %>" + +.. describe:: job_name (String, nil) + + The name of the job. + + Default + Not set initially, but specified by OnDemand system automatically. + + .. code-block:: yaml + + job_name: nil + + Example + **None given because users cannot specify this in batch connect applications.** + +.. describe:: shell_path (String, nil) + + The login shell path of the script. + + Default + Not set initially, but specified by OnDemand system automatically. + + .. code-block:: yaml + + shell_path: nil + + Example + **None given because users cannot specify this in batch connect applications.** + +.. describe:: error_path (String, nil) + + The path for the standard error of the job. + + Default + Not set initially, but specified by OnDemand system automatically. + + .. code-block:: yaml + + error_path: nil + + Example + **None given because users cannot specify this in batch connect applications.** + +.. describe:: input_path (String, nil) + + Use this file for standard input for the job's script. + Batch connect applications do not expect to read anything + from standard in. + + Default + Not set. + + .. code-block:: yaml + + input_path: nil + + Example + **None given because this is likely to break batch connect applications.** + +.. describe:: output_path (String, nil) + + The path for the standard output of the job. + + Default + Not set initially, but specified by OnDemand system automatically. + + .. code-block:: yaml + + output_path: nil + + Example + **None given because users cannot specify this in batch connect applications.** + +.. describe:: reservation_id (String, nil) + + The reservation id the job will submit to. + + Default + Not specified. + + .. code-block:: yaml + + reservation_id: nil + + Example + Submit jobs to the ``next.may.2020`` reservation. + + .. code-block:: yaml + + reservation_id: "next.may.2020" + +.. describe:: queue_name (String, nil) + + The queue the job will submit to. + + .. tip:: + Users can use :ref:`bc_queue ` for a text field and + :ref:`auto_queues ` for a select widget. Both of these + form fields know how to submit to schedulers, removing + the need to use this field in this file. + + Default + Not specified. + + .. code-block:: yaml + + queue_name: nil + + Example + Submit jobs to the ``debug`` queue. + + .. code-block:: yaml + + queue_name: "debug" + +.. describe:: priority (String, nil) + + The priority the job has. + + Default + Not specified. + + .. code-block:: yaml + + priority: nil + + Example + Submit jobs with ``TOP`` priority. + + .. code-block:: yaml + + priority: "TOP" + +.. describe:: start_time (String, nil) + + The start time of the job. + + Default + Not set, which schedulers generally interpret as now or as soon as possible. + + .. code-block:: yaml + + start_time: nil + + Example + Start at midnight. + + .. code-block:: yaml + + start_time: "00:00:00" + +.. describe:: wall_time (Integer, nil) + + The wall time of the job in seconds. + + .. tip:: + Users can use :ref:`bc_num_hours ` for a number field + that knows how to submit to schedulers, removing + the need to use this field in this file. + + Default + Not specified. + + .. code-block:: yaml + + wall_time: nil + + Example + Always limit this job to one hour. + + .. code-block:: yaml + + wall_time: 3600 + +.. describe:: accounting_id (String, nil) + + The accounting id the job should be charged to. + + .. tip:: + Users can use :ref:`bc_account ` for a text field and + :ref:`auto_accounts ` or :ref:`auto_accounts ` + for a select widget. + + All of these form fields know how to submit to schedulers, removing + the need to use this field in this file. + + Default + Not specified, uses the schedulers' default. + + .. code-block:: yaml + + priority: nil + + Example + All jobs to use the ``rstudio-class-account`` accounting id. + + .. code-block:: yaml + + accounting_id: 'rstudio-class-account' + +.. describe:: native (Object, nil) + + Native arguments to pass to the schedulers' submit command. + + .. warning:: + All schedulers use Array for native attributes except for Torque. + Torque schedulers use Hash. + + Default + not specified + + .. code-block:: yaml + + native: nil + + Example + Submit the job with SLURM requests for one node, ``num_cores`` (a form variable) + cores and ``memory`` (another form variable) amount of memory. + + .. code-block:: yaml + + native: + - "-N" + - "1" + - "-n" + - "<%= num_cores %>" + - "--mem" + - "<%= memory %>" + +.. describe:: copy_environment (Boolean, nil) + + Have the scheduler to copy the environment. SLURM uses + ``--export=ALL`` (OnDemand's default is NONE). PBS/Torque and LSF + set the ``-V`` flag. + + Default + not specified + + .. code-block:: yaml + + native: nil + + Example + Copy the environment + + .. code-block:: yaml + + copy_environment: true + + +.. _ood_core gem Ruby docs: https://osc.github.io/ood_core/OodCore/Job/Script.html \ No newline at end of file diff --git a/source/reference/files/submit-yml/vnc-bc-options.rst b/source/reference/files/submit-yml/vnc-bc-options.rst new file mode 100644 index 000000000..026ec663a --- /dev/null +++ b/source/reference/files/submit-yml/vnc-bc-options.rst @@ -0,0 +1,226 @@ +.. _vnc-bc-options: + +Batch Connect VNC Options +========================= + + +All the options in :ref:`basic-bc-options` apply in addition to what's listed below. + + .. code-block:: yaml + + batch_connect: + template: "vnc" + conn_params: + - host + - port + - password + - spassword + - display + - websocket + websockify_cmd: "/opt/websockify/run" + vnc_passwd: "vnc.passwd" + vnc_args: nil + name: "" + geometry: "" + dpi: "" + fonts: "" + idle: "" + extra_args: "" + vnc_clean: "..." + + +.. describe:: websockfiy_cmd (String, "/opt/websockify/run") + + the command to start websockify + + Default + the '/opt/websockify/run' command + + .. code-block:: yaml + + websockfiy_cmd: "/opt/websockify/run" + + Example + the '/usr/bin/websockify' command + + .. code-block:: yaml + + websockify_cmd: "/usr/bin/websockify" + +.. describe:: vnc_passwd (String, "vnc.passwd") + + the file vncserver will read for a password + + Default + a file named 'vnc.passwd' + + .. code-block:: yaml + + vnc_passwd: "vnc.passwd" + + Example + a file named 'my-other-vnc.passwd' + + .. code-block:: yaml + + vnc_passwd: "my-other-vnc.passwd" + +.. describe:: vnc_args (String, "") + + vnc arguments to use instead of the specific options + ``name``, ``geometry``, ``dpi``, ``fonts``, ``idle`` and + ``extra_args``. + + Default + no arguments + + .. code-block:: yaml + + vnc_args: "" + + Example + only specify the xstartup option + + .. code-block:: yaml + + vnc_args: "-xstartup /opt/vnc/startup.sh" + +.. describe:: name (String, "") + + the desktop name + + Default + do not specify name, vncserver defaults to ``host:display# (username)`` + + .. code-block:: yaml + + name: "" + + Example + boot vncserver with ``-name ood-$USER-$DISPLAY`` argument + + .. code-block:: yaml + + name: "ood-ood-$USER-$DISPLAY" + +.. describe:: geometry (String, "") + + the geometry size of the VNC desktop + + Default + do not specify geometry, turbovnc defaults to ``1240x900`` + + .. code-block:: yaml + + geometry: "" + + Example + boot vncserver with ``-geometry 1920x1080`` argument + + .. code-block:: yaml + + geometry: "1920x1080" + +.. describe:: dpi (String, "") + + the dots per inch setting of the VNC desktop + + Default + do not specify dpi + + .. code-block:: yaml + + dpi: "" + + Example + boot vncserver with ``-dpi 96`` argument + + .. code-block:: yaml + + dpi: "96" + +.. describe:: fonts (String, "") + + the font path for X11 fonts + + Default + do not specify -fp option + + .. code-block:: yaml + + fonts: "" + + Example + boot vncserver with ``-fp unix/:7100`` argument + + .. code-block:: yaml + + fonts: "unix/:7100" + +.. describe:: idle (String, "") + + the idle timeout setting for the vncserver + + Default + do not specify -idletimeout option + + .. code-block:: yaml + + idle: "" + + Example + boot vncserver with ``-idletimeout 3600`` argument + + .. code-block:: yaml + + idle: "3600" + +.. describe:: extra_args (String, "") + + any extra arguments to pass into vncserver + + Default + do not specify extra arguments + + .. code-block:: yaml + + idle: "" + + Example + set the color depth of the vncserver to 32, in addition to any + other specific argument given above + + .. code-block:: yaml + + extra_args: "-depth 32" + +.. warning:: + These items below should not be set by users. They are + given for completeness only. It's likely they'll cause + errors if overridden. + +.. describe:: conn_params (Array, + ['host','port','password','spassword','display','websocket']) + + the connection parameters that will be written to the ``conn_file`` + + Default + 'host', 'port', 'password', 'spassword', 'display' and 'websocket' + + .. code-block:: yaml + + conn_params: + - 'host' + - 'port' + - 'password' + - 'spassword' + - 'display' + - 'websocket' + + Example + The API to connect to can change in the ``script.sh.erb`` based off of + something that can only be determined during the job (for example an + environment variable in a module). + + conn_params: + - the_connect_api \ No newline at end of file