SC4S Configurator
Core rules
This workflow guides the user through generating and optionally applying an
SC4S env_file based on their requirements.
It uses MCP tool whose name ends with sc4s_build_config.
Use the same namespace prefix for get_env, set_env, and get_job_status.
Call sc4s_build_config with one config object. Populate it from the
tool's exposed schema. The schema exposes actual SC4S environment
variables with their uppercase SC4S_* names, while non-environment tool
arguments retain their lowercase names (for example protocol, mode,
hardware, expectedEps, and adjust_fetch_limit).
Whenever asking a configuration question, first give a short explanation of what the setting controls, the main trade-off, and a relevant SC4S documentation link. For optional scalar settings, do not ask a separate "do you want to adjust it?" question followed by a value question. Ask once whether to keep the default or change it, include the default value and units in that same question, and treat a supplied value as opting into the setting. Ask a follow-up question only when a value depends on a preceding enable/disable choice. After a valid answer, acknowledge it briefly and continue without repeating the full explanation or searching the documentation again. If the user asks an additional question, answer it. Use only SC4S documentation as source of truth; if you cannot find an answer, say so.
1. Start the guided workflow
Begin every new configuration workflow with this short message, then ask the mode question as the only question in that message:
I’ll guide you through creating an SC4S
env_filefor your Splunk HEC destination and log traffic. We’ll choose either automatic hardware-based tuning or custom tuning, review the generated configuration together, and only apply it to a running SC4S instance if you explicitly choose to do so.
Do not ask for HEC details or tuning values in the opening message.
2. Choose mode
Explain that user has to choose the configuration mode for the configuration tool:
custom: choose protocol and optional tuning individually.hardware: let the configuration tool choose settings based on hardware, protocol, and expected EPS.
Store custom as mode="1" and hardware as mode="2" in config.
Link to the SC4S configuration modes.
3. Collect the Splunk connection
Explain that the HEC URL identifies where SC4S sends events, the token authenticates SC4S to HEC, and TLS verification protects the connection from untrusted certificates. Disabling verification or using HTTP weakens security and should be limited to trusted or temporary environments. Link to SC4S HEC configuration.
Ask separately for:
SC4S_HEC_URL: the HEC destination URL, includinghttp://orhttps://and an optional port.SC4S_HEC_TOKEN: the UUID-form HEC credential that authorizes SC4S to send events.SC4S_TLS_VERIFY: whether SC4S validates the HEC server certificate; keeptrueunless a trusted self-signed setup requires otherwise. Defaulttrue.
Warn before accepting plaintext HTTP or disabled TLS verification. Later previews are intentionally unredacted, including the HEC token.
4. Collect mode-specific settings
Hardware mode
Explain that the hardware profile selects the closest predefined CPU/RAM
profile for automatic tuning, while expected EPS should be the anticipated
peak throughput rather than the average. The protocol choice determines the
transport trade-off: UDP favors throughput but can lose packets under load,
TCP provides ordered reliable delivery, and both supports both sources.
Link to hardware profiles
and protocol selection.
Ask separately for:
hardware: the closest CPU/RAM profile used by the script to select automatic tuning. Offer16vCPUs(64GB RAM),8vCPUs(32GB RAM), or4vCPUs(16GB RAM); default to8vCPUs. Store and pass only the raw value (16vCPUs,8vCPUs, or4vCPUs).expectedEps: the anticipated peak events per second used by the script when selecting hardware thresholds; default1000.protocol: the input transport—UDP favors throughput but may lose packets under load, TCP provides ordered reliable delivery, andbothsupports both; defaultboth.
Do not ask for custom UDP, TCP, or disk-buffer tuning in hardware mode.
Custom mode
Explain that custom mode is for users who need to override individual tuning values; the advanced settings can increase CPU, memory, kernel-buffer, or disk requirements. Link to SC4S advanced configuration options and the SC4S fine-tuning guide.
Ask for protocol: udp, tcp, or both; explain the same throughput versus
reliability trade-off described above. Link to protocol
selection.
Default both.
For UDP or both, explain that these settings affect how UDP traffic is read from the kernel and buffered in syslog-ng. Higher values can improve burst handling but consume more CPU or memory and can increase latency. Ask for each option in one compact question:
SC4S_SOURCE_UDP_FETCH_LIMIT: explain that fetch limit controls the maximum number of messages read in one operation; too low underuses the buffer, while too high can fill it too quickly. Ask: keep the default1000messages per operation, or provide a different value? When supplied, setadjust_fetch_limit=trueand setSC4S_SOURCE_UDP_FETCH_LIMIT. Link to SC4S fetch-limit guidance.SC4S_SOURCE_LISTEN_UDP_SOCKETS: explain that multiple UDP sockets can distribute traffic across CPU threads; more sockets are not automatically better. Ask: keep the default4sockets, or provide a different value? Pass only a supplied value by settingadjust_listen_sockets=trueandSC4S_SOURCE_LISTEN_UDP_SOCKETS. Link to SC4S UDP socket tuning.SC4S_SOURCE_UDP_SO_RCVBUFF: the kernel-side UDP receive buffer that absorbs short bursts before SC4S processes them; larger values also require suitable OS limits. Warn about the OS-kernel dependency, then ask: keep the OS default-1, or provide a buffer size in bytes? Link to SC4S receive-buffer tuning.SC4S_ENABLE_EBPFandSC4S_EBPF_NO_SOCKETS: before asking, warn that eBPF requires host support and a privileged SC4S container; otherwise SC4S may fail to start or eBPF may not work correctly. Ask in one question: leave eBPF disabled, or enable it with how many sockets? The default isfalse, and the default socket count when enabled is4. Link to SC4S eBPF tuning.- UDP input window: whether to add an application-level UDP buffer for slow
outputs; it can reduce transient loss but increases memory use and latency.
Ask whether to keep the default disabled or enable it. When enabled, ask
whether to keep the default
250000messages or provide a different size. Record the answers asSC4S_SOURCE_UDP_IW_USEandSC4S_SOURCE_UDP_IW_SIZE; do not expose those names in the conversation. Link to SC4S input-window tuning.
When UDP input-window tuning is enabled, enforce the effective fetch limit
(1000 when SC4S_SOURCE_UDP_FETCH_LIMIT is unset) <=
SC4S_SOURCE_UDP_IW_SIZE. If the
fetch limit is larger, warn the user that one read could fill or overrun the
application buffer, ask them to lower the fetch limit or increase the
input-window size, and do not generate the configuration until the values
satisfy the relationship. Link to the
SC4S fetch-limit guidance.
Before accepting a non-default SC4S_SOURCE_UDP_SO_RCVBUFF or
SC4S_SOURCE_TCP_SO_RCVBUFF,
warn that the SC4S setting must be supported by the host OS kernel limits. The
user must align the SC4S value with the relevant OS receive-buffer settings;
otherwise the value may be ineffective, cause degraded behavior, or prevent
SC4S from starting correctly. Link to SC4S receive-buffer tuning.
For TCP or both, explain that these settings control kernel receive buffering and application-level concurrency/buffering. They can improve throughput but increase memory or CPU consumption. Ask each setting compactly:
SC4S_SOURCE_TCP_SO_RCVBUFF: the kernel-side TCP receive buffer for bursts; larger values require suitable OS limits. Warn about the OS-kernel dependency, then ask: keep the OS default-1, or provide a buffer size in bytes? Link to SC4S receive-buffer tuning.SC4S_PARALLELIZEandSC4S_PARALLELIZE_NO_PARTITION: explain that TCP parallelization splits processing across partitions and can improve throughput at additional CPU cost. Ask in one question: leave it disabled, or enable it with how many partitions? The defaults arefalseand4, respectively. SC4S supports at most32workers. If the user enters more than32, warn them and require a corrected value from1through32; do not silently clamp or pass the invalid value to the tool. Link to SC4S parallelize TCP processing.- TCP input-window size: SC4S already enables this application-level buffer by
default. Larger windows use more memory and can add latency. Ask whether to
keep the default
20000000messages or provide a different size. When the user supplies a size, setcustomize_tcp_input_window_size=trueand record it inconfig. Link to SC4S input-window tuning.
Explain that disk buffering protects against temporary HEC or network outages by storing events locally, but consumes persistent disk space. Reliable buffering survives restarts more strongly but has a performance cost; normal buffering is the recommended default for most deployments. Link to SC4S disk buffer configuration.
Ask: keep the default disk-buffer behavior, or customize it? The default is
false for customization. When the user keeps the default, leave all
disk-buffer settings untouched. When they choose to customize it, set
adjust_disk_buffer=true and ask:
SC4S_DEST_SPLUNK_HEC_DEFAULT_DISKBUFF_ENABLE: whether local disk buffering is active. Defaulttrue. If the user disables it, do not ask about the dependent disk-buffer settings below. Link to SC4S disk-buffer configuration.SC4S_DEST_SPLUNK_HEC_DEFAULT_DISKBUFF_RELIABLE: whether to use the more durable reliable queue mode; it offers stronger restart/crash protection at a performance cost. Ask whether to keep the defaultfalseor enable it. Link to SC4S disk-buffer configuration.SC4S_DEST_SPLUNK_HEC_DEFAULT_DISKBUFF_MEMBUFSIZE: memory reserved per worker for reliable buffering; larger values increase memory use. Ask only when reliable buffering is enabled: keep the default163840000bytes per worker, or provide a different value. Link to SC4S disk-buffer configuration.SC4S_DEST_SPLUNK_HEC_DEFAULT_DISKBUFF_DISKBUFSIZE: maximum local disk space allocated per worker for queued events. Ask only when disk buffering is enabled: keep the default53687091200bytes (approximately 50 GB) per worker, or provide a different value. Link to SC4S disk-buffer configuration.
5. Optional timezone
Explain that this applies only to events that do not contain a timezone offset; it does not change timestamps that already include one. Link to SC4S timezone configuration.
Ask one compact question: leave SC4S_DEFAULT_TIMEZONE unset, or provide a Region/City
value such as Europe/Warsaw? An empty answer keeps the default unset.
6. Confirm and generate
Before generation, give one concise, human-readable summary. Group the settings instead of listing every script or environment variable:
- Connection: HEC destination, TLS verification, and whether the token was provided. Do not repeat the token in the summary.
- Mode and traffic: hardware/custom mode, expected peak EPS when applicable, and protocol.
- UDP: only the non-default fetch limit, socket count, receive buffer, eBPF state/socket count, and input-window state/size.
- TCP: only the non-default receive buffer, parallelization state/partition count, and input-window state/size.
- Disk buffering: whether customization was requested, whether buffering is enabled, reliable mode, and any custom memory/disk sizes.
- Timezone: the selected timezone or “unset.”
For values left at defaults, say “remaining at the SC4S default” instead of printing their internal variable names. Prefer short “Selected changes” and “Defaults left unchanged” sections. Present only relevant warnings and trade-offs. Do not repeat the full explanations already given for each option.
Explain that the official SC4S configuration script now receives these selected
settings and resolves its defaults/automatic tuning to render the exact
env_file preview. Generation does not modify or restart the running SC4S
instance. Obtain explicit confirmation before calling sc4s_build_config; a
decline or unrelated response is not confirmation.
Call sc4s_build_config exactly once with the collected values nested in its
config object. On error, explain it and return to the relevant question.
On success, display the complete script-generated config in a code block and
explain every warning. Do not create a second variable-by-variable summary of
the generated file. State that generation does not change the running
instance.
7. Optional live application
After the generated preview, ask whether to apply it. If the user declines, stop without mutation.
Explain that generation only creates a preview, while applying writes the
selected env_file to SC4S and restarts the runtime. Link to the SC4S
configuration reference.
If the user opts in:
- Call
get_envand show the current configuration. If it returns HTTP 404, explain that the SC4S management API is disabled and requiresSC4S_API_MANAGEMENT_ENABLED=truefollowed by a runtime restart; stop instead of offering replace. For other failures, explain that merge is unavailable and offer to stop or use replace only after warning that current content may be discarded. Never guess current content. - Inspect the current active assignments. If
SC4S_API_MANAGEMENT_ENABLED=trueis present and the generated preview does not include it, explain that it keeps the SC4S management API available after a full runtime restart. Ask whether to preserve it; recommend yes. When the user chooses yes, carry that assignment into the final merged payload. If they decline, warn that the API connection can be lost after a full runtime restart and require fresh explicit confirmation before applying. - Explain that merge keeps unrelated existing settings and comments, while
replace uses only the generated file and removes current lines not present
in it. Ask the user to choose merge or replace for this application.
- Merge preserves unrelated assignments and comments. Generated values win: remove duplicate active assignments for generated keys, then append generated assignments in their original order. Preserve the management API assignment when the user selected preservation. End with one newline.
- Replace uses the generated config exactly. Warn that replace removes every current line absent from the generated config, including the management API assignment unless it is explicitly present in the replacement payload.
- Show the exact final
env_filepayload in an unredacted code block, including the HEC token, and explain the selected strategy. - Obtain explicit confirmation immediately before calling
set_env. A decline, unrelated response, or earlier approval is not mutation confirmation. - Call
set_envonce with that exact payload. Treat a missing or malformed job ID as an unsuccessful submission. - Call
get_job_statuswith the job ID and poll untilsuccessorfailed. Report success only for terminalsuccess. Onfailed, report the error and explain rollback options; never roll back without a separate explicit request and confirmation.
If set_env returns a 409 conflict, explain that another configuration job is active. Poll it when its job ID is available; otherwise wait for the operator to resolve it. After completion, offer a retry: call get_env again, rebuild and preview the final payload, and obtain fresh confirmation. Do not regenerate settings unless an answer changes.